feat(filter): Add filter method (#7127)

**Related Issue:** #6633

## Summary

- Adds public filter method to the calcite-filter component.
- Fixes setting `filteredItems` on filter.
- Adds test

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

@@ -274,6 +274,52 @@ describe("calcite-filter", () => {
     });
   });
 
+  describe("filter method", () => {
+    let page: E2EPage;
+
+    beforeEach(async () => {
+      page = await newE2EPage();
+      await page.setContent(`<calcite-filter></calcite-filter>`);
+      await page.evaluate(() => {
+        const filter = document.querySelector("calcite-filter");
+        filter.items = [
+          {
+            name: "Harry",
+            description: "developer",
+            value: "harry",
+            metadata: { haircolor: "red", favoriteBand: "MetallicA" }
+          },
+          {
+            name: "Matt",
+            description: "developer",
+            value: "matt",
+            metadata: { haircolor: "black", favoriteBand: "Radiohead" }
+          }
+        ];
+      });
+    });
+
+    it("should filter with value argument", async () => {
+      const filter = await page.find("calcite-filter");
+      const filterChangeSpy = await page.spyOnEvent("calciteFilterChange");
+      await filter.callMethod("filter", "Matt");
+      await page.waitForChanges();
+      expect(filterChangeSpy).toHaveReceivedEventTimes(0);
+      assertMatchingItems(await filter.getProperty("filteredItems"), ["matt"]);
+    });
+
+    it("should filter without value argument", async () => {
+      const filter = await page.find("calcite-filter");
+      filter.setProperty("value", "harry");
+      await page.waitForChanges();
+      const filterChangeSpy = await page.spyOnEvent("calciteFilterChange");
+      await filter.callMethod("filter");
+      await page.waitForChanges();
+      expect(filterChangeSpy).toHaveReceivedEventTimes(0);
+      assertMatchingItems(await filter.getProperty("filteredItems"), ["harry"]);
+    });
+  });
+
   describe("translation support", () => {
     t9n("calcite-filter");
   });

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

@@ -66,7 +66,7 @@ export class Filter
 
   @Watch("items")
   watchItemsHandler(): void {
-    this.filter(this.value);
+    this.filterDebounced(this.value);
   }
 
   /**
@@ -117,7 +117,7 @@ export class Filter
 
   @Watch("value")
   valueHandler(value: string): void {
-    this.filter(value);
+    this.filterDebounced(value);
   }
 
   // --------------------------------------------------------------------------
@@ -176,6 +176,7 @@ export class Filter
     disconnectInteractive(this);
     disconnectLocalized(this);
     disconnectMessages(this);
+    this.filterDebounced.cancel();
   }
 
   componentDidLoad(): void {
@@ -188,6 +189,22 @@ export class Filter
   //
   // --------------------------------------------------------------------------
 
+  /**
+   * Performs a filter on the component.
+   *
+   * This method can be useful because filtering is delayed and asynchronous.
+   *
+   * @param {string} value - The filter text value.
+   * @returns {Promise<void>}
+   */
+  @Method()
+  async filter(value: string = this.value): Promise<void> {
+    return new Promise((resolve) => {
+      this.value = value;
+      this.filterDebounced(value, false, resolve);
+    });
+  }
+
   /** Sets focus on the component. */
   @Method()
   async setFocus(): Promise<void> {
@@ -202,15 +219,16 @@ export class Filter
   //
   // --------------------------------------------------------------------------
 
-  private filter = debounce(
-    (value: string, emit = false): void => this.updateFiltered(filter(this.items, value), emit),
+  private filterDebounced = debounce(
+    (value: string, emit = false, onFilter?: () => void): void =>
+      this.updateFiltered(filter(this.items, value), emit, onFilter),
     DEBOUNCE_TIMEOUT
   );
 
   inputHandler = (event: CustomEvent): void => {
     const target = event.target as HTMLCalciteInputElement;
     this.value = target.value;
-    this.filter(target.value, true);
+    this.filterDebounced(target.value, true);
   };
 
   keyDownHandler = (event: KeyboardEvent): void => {
@@ -226,16 +244,16 @@ export class Filter
 
   clear = (): void => {
     this.value = "";
-    this.filter("", true);
+    this.filterDebounced("", true);
     this.setFocus();
   };
 
-  updateFiltered(filtered: any[], emit = false): void {
-    this.filteredItems.length = 0;
-    this.filteredItems = this.filteredItems.concat(filtered);
+  updateFiltered(filtered: object[], emit = false, callback?: () => void): void {
+    this.filteredItems = filtered;
     if (emit) {
       this.calciteFilterChange.emit();
     }
+    callback?.();
   }
 
   // --------------------------------------------------------------------------