feat: add configurable debounce interval for datasource filter

Author: yordan-st

packages/pluggableWidgets/combobox-web/CHANGELOG.md

@@ -15,6 +15,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - We fixed an issue where combobox lazy load is not working on initial load.
 
+### Added
+
+- We added a configurable debounce interval for datasource filter operations via a new property in the Advanced tab.
+
 ## [2.5.0] - 2025-08-12
 
 ### Added

packages/pluggableWidgets/combobox-web/src/Combobox.editorConfig.ts

@@ -152,6 +152,7 @@ export function getProperties(
             "selectionMethod",
             "selectAllButton",
             "selectAllButtonCaption",
+            "datasourceFilterDebounceInterval",
             ...ASSOCIATION_SOURCE_CONFIG,
             ...DATABASE_SOURCE_CONFIG,
             ...LAZY_LOADING_CONFIG

packages/pluggableWidgets/combobox-web/src/Combobox.xml

@@ -417,6 +417,10 @@
                         <enumerationValue key="skeleton">Skeleton</enumerationValue>
                     </enumerationValues>
                 </property>
+                <property key="datasourceFilterDebounceInterval" type="integer" required="true" defaultValue="200">
+                    <caption>Filter debounce</caption>
+                    <description>Debounce interval in milliseconds.</description>
+                </property>
             </propertyGroup>
             <propertyGroup caption="Multiple-selection">
                 <property key="selectedItemsSorting" type="enumeration" defaultValue="none" required="true">

packages/pluggableWidgets/combobox-web/src/__tests__/MultiSelection.spec.tsx

@@ -77,7 +77,8 @@ describe("Combo box (Association)", () => {
             selectedItemsSorting: "none",
             customEditability: "default",
             customEditabilityExpression: dynamic(false),
-            filterInputDebounceInterval: 200
+            filterInputDebounceInterval: 200,
+            datasourceFilterDebounceInterval: 200
         };
         if (defaultProps.optionsSourceAssociationCaptionType === "expression") {
             defaultProps.optionsSourceAssociationCaptionExpression!.get = i => dynamic(`${i.id}`);

packages/pluggableWidgets/combobox-web/src/__tests__/SingleSelection.spec.tsx

@@ -80,7 +80,8 @@ describe("Combo box (Association)", () => {
             selectedItemsSorting: "none",
             customEditability: "default",
             customEditabilityExpression: dynamic(false),
-            filterInputDebounceInterval: 200
+            filterInputDebounceInterval: 200,
+            datasourceFilterDebounceInterval: 200
         };
         if (defaultProps.optionsSourceAssociationCaptionType === "expression") {
             defaultProps.optionsSourceAssociationCaptionExpression!.get = i => dynamic(`${i.id}`);

packages/pluggableWidgets/combobox-web/src/__tests__/StaticSelection.spec.tsx

@@ -78,7 +78,8 @@ describe("Combo box (Static values)", () => {
             selectedItemsSorting: "none",
             customEditability: "default",
             customEditabilityExpression: dynamic(false),
-            filterInputDebounceInterval: 200
+            filterInputDebounceInterval: 200,
+            datasourceFilterDebounceInterval: 200
         };
         if (defaultProps.optionsSourceAssociationCaptionType === "expression") {
             defaultProps.optionsSourceAssociationCaptionExpression!.get = i => dynamic(`${i.id}`);

packages/pluggableWidgets/combobox-web/src/helpers/Association/BaseAssociationSelector.ts

@@ -45,7 +45,8 @@ export class BaseAssociationSelector<T extends string | string[], R extends Refe
             customContent,
             customContentType,
             lazyLoading,
-            loadingType
+            loadingType,
+            datasourceFilterDebounceInterval
         ] = extractAssociationProps(props);
 
         this.lazyLoader.updateProps(ds);
@@ -64,7 +65,8 @@ export class BaseAssociationSelector<T extends string | string[], R extends Refe
             ds,
             filterType,
             lazyLoading,
-            attributeId: captionType === "attribute" ? (captionProvider as ListAttributeValue<string>).id : undefined
+            attributeId: captionType === "attribute" ? (captionProvider as ListAttributeValue<string>).id : undefined,
+            datasourceFilterDebounceInterval
         });
 
         if (

packages/pluggableWidgets/combobox-web/src/helpers/Association/utils.ts

@@ -28,13 +28,15 @@ type ExtractionReturnValue = [
     ListWidgetValue | undefined,
     OptionsSourceAssociationCustomContentTypeEnum,
     boolean,
-    LoadingTypeEnum
+    LoadingTypeEnum,
+    number
 ];
 
 export function extractAssociationProps(props: ComboboxContainerProps): ExtractionReturnValue {
     const attr = props.attributeAssociation;
     const filterType = props.filterType;
     const onChangeEvent = props.onChangeEvent;
+    const datasourceFilterDebounceInterval = props.datasourceFilterDebounceInterval;
 
     if (!attr) {
         throw new Error("'optionsSourceType' type is 'association' but 'attributeAssociation' is not defined.");
@@ -79,6 +81,7 @@ export function extractAssociationProps(props: ComboboxContainerProps): Extracti
         customContent,
         customContentType,
         lazyLoading,
-        loadingType
+        loadingType,
+        datasourceFilterDebounceInterval
     ];
 }

packages/pluggableWidgets/combobox-web/src/helpers/BaseDatasourceOptionsProvider.ts

@@ -1,3 +1,4 @@
+import { debounce } from "@mendix/widget-plugin-platform/utils/debounce";
 import { ListAttributeValue, ListValue, ObjectItem } from "mendix";
 import { FilterTypeEnum } from "../../typings/ComboboxProps";
 import { BaseOptionsProvider } from "./BaseOptionsProvider";
@@ -10,12 +11,16 @@ export interface BaseProps {
     ds: ListValue;
     filterType: FilterTypeEnum;
     lazyLoading: boolean;
+    datasourceFilterDebounceInterval?: number;
 }
 
 export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectItem, BaseProps> {
     private ds?: ListValue;
     private attributeId?: ListAttributeValue["id"];
     protected loading: boolean = false;
+    private debouncedSetFilter?: (filterCondition: any) => void;
+    private abortDebouncedFilter?: () => void;
+    private datasourceFilterDebounceInterval: number = 200;
 
     constructor(
         caption: CaptionsProvider,
@@ -24,6 +29,19 @@ export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectIte
         super(caption);
     }
 
+    private createDebouncedSetFilter(): void {
+        if (this.abortDebouncedFilter) {
+            this.abortDebouncedFilter();
+        }
+
+        const [debouncedFn, abort] = debounce((filterCondition: any) => {
+            this.ds?.setFilter(filterCondition);
+        }, this.datasourceFilterDebounceInterval);
+
+        this.debouncedSetFilter = debouncedFn;
+        this.abortDebouncedFilter = abort;
+    }
+
     get sortOrder(): SortOrder {
         let sortDir: SortOrder = "asc";
         if (this.ds) {
@@ -50,11 +68,14 @@ export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectIte
 
     getAll(): string[] {
         if (this.lazyLoading && this.attributeId) {
+            if (!this.debouncedSetFilter) {
+                this.createDebouncedSetFilter();
+            }
             if (this.searchTerm === "") {
-                this.ds?.setFilter(undefined);
+                this.debouncedSetFilter!(undefined);
             } else {
                 const filterCondition = datasourceFilter(this.filterType, this.searchTerm, this.attributeId);
-                this.ds?.setFilter(filterCondition);
+                this.debouncedSetFilter!(filterCondition);
             }
 
             return this.options;
@@ -88,8 +109,12 @@ export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectIte
     // used for initial load of selected value in case options are lazy loaded
     loadSelectedValue(attributeValue: string, attrId?: ListAttributeValue["id"]): void {
         if (this.lazyLoading && this.ds && this.attributeId) {
+            if (!this.debouncedSetFilter) {
+                this.createDebouncedSetFilter();
+            }
+
             const filterCondition = datasourceFilter("containsExact", attributeValue, attrId ?? this.attributeId);
-            this.ds?.setFilter(filterCondition);
+            this.debouncedSetFilter!(filterCondition);
             this.ds.setLimit(1);
         }
     }
@@ -100,6 +125,12 @@ export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectIte
         this.filterType = props.filterType;
         this.lazyLoading = props.lazyLoading;
 
+        const newInterval = props.datasourceFilterDebounceInterval ?? 200;
+        if (newInterval !== this.datasourceFilterDebounceInterval) {
+            this.datasourceFilterDebounceInterval = newInterval;
+            this.createDebouncedSetFilter();
+        }
+
         if (this.lazyLoading) {
             if (props.ds.status === "loading") {
                 this.loading = true;
@@ -113,4 +144,10 @@ export class BaseDatasourceOptionsProvider extends BaseOptionsProvider<ObjectIte
         items.forEach(i => this.valuesMap.set(i.id, i));
         this.options = Array.from(this.valuesMap.keys());
     }
+
+    cleanup(): void {
+        if (this.abortDebouncedFilter) {
+            this.abortDebouncedFilter();
+        }
+    }
 }

packages/pluggableWidgets/combobox-web/src/helpers/Database/DatabaseMultiSelectionSelector.ts

@@ -75,7 +75,8 @@ export class DatabaseMultiSelectionSelector implements MultiSelector {
             filterType,
             lazyLoading,
             loadingType,
-            valueSourceAttribute
+            valueSourceAttribute,
+            datasourceFilterDebounceInterval
         } = extractDatabaseProps(props);
 
         if (
@@ -107,7 +108,8 @@ export class DatabaseMultiSelectionSelector implements MultiSelector {
             ds,
             filterType,
             lazyLoading,
-            attributeId: captionType === "attribute" ? (captionProvider as ListAttributeValue<string>).id : undefined
+            attributeId: captionType === "attribute" ? (captionProvider as ListAttributeValue<string>).id : undefined,
+            datasourceFilterDebounceInterval
         });
 
         if (this.selectionMethod === "rowclick" || this.customContentType === "yes") {