docs: combo box lazy loading (#4199)

* add react example

* add lit example

* add flow example

* Update articles/components/combo-box/index.adoc

Co-authored-by: Soroosh Taefi <taefi.soroosh@gmail.com>

---------

Co-authored-by: Soroosh Taefi <taefi.soroosh@gmail.com>

Author: sissbruecker

articles/components/combo-box/index.adoc

@@ -333,6 +333,59 @@ endif::[]
 --
 
 
+== Lazy Loading
+
+Combo Box supports lazy loading, which is useful when dealing with large datasets. This avoids loading the whole dataset into memory and only fetches data for the current filter and viewport.
+
+[.example]
+--
+ifdef::lit[]
+[source,typescript]
+----
+include::{root}/frontend/demo/component/combobox/combo-box-lazy-loading.ts[render,tags=snippet,indent=0,group=Lit]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryService.java[render,tags=snippet,indent=0,group=Lit]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryRepository.java[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxLazyLoading.java[render,tags=snippet,indent=0,group=Flow]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryService.java[render,tags=snippet,indent=0,group=Flow]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryRepository.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/combobox/react/combo-box-lazy-loading.tsx[render,tags=snippet,indent=0,group=React]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryService.java[render,tags=snippet,indent=0,group=React]
+----
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryRepository.java[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+--
+
+
 // Basic Features
 
 include::{articles}/components/_input-field-common-features.adoc[tags=basic-intro;label;helper;placeholder;tooltip;clear-button;prefix;aria-labels]

frontend/demo/component/combobox/combo-box-lazy-loading.ts

@@ -0,0 +1,59 @@
+import 'Frontend/demo/init'; // hidden-source-line
+import '@vaadin/combo-box';
+import { html, LitElement } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type {
+  ComboBoxDataProviderCallback,
+  ComboBoxDataProviderParams,
+} from '@vaadin/react-components';
+import type Country from 'Frontend/generated/com/vaadin/demo/domain/Country';
+import { ComboBoxCountryService } from 'Frontend/generated/endpoints';
+import { applyTheme } from 'Frontend/generated/theme';
+
+@customElement('combo-box-lazy-loading')
+export class Example extends LitElement {
+  protected override createRenderRoot() {
+    const root = super.createRenderRoot();
+    // Apply custom theme (only supported if your app uses one)
+    applyTheme(root);
+    return root;
+  }
+
+  // tag::snippet[]
+  async dataProvider(
+    params: ComboBoxDataProviderParams,
+    callback: ComboBoxDataProviderCallback<Country>
+  ) {
+    // Convert the params to Spring Data Pageable
+    const filter = params.filter;
+    const pageable = {
+      pageNumber: params.page,
+      pageSize: params.pageSize,
+      sort: { orders: [] },
+    };
+    // Call backend service with pageable and current combo box filter
+    const pageItems = await ComboBoxCountryService.list(pageable, filter);
+
+    // Estimate the total count of filtered items
+    let filteredCount;
+    if (pageItems.length === params.pageSize) {
+      filteredCount = (params.page + 1) * params.pageSize + 1;
+    } else {
+      filteredCount = params.page * params.pageSize + pageItems.length;
+    }
+
+    callback(pageItems, filteredCount);
+  }
+
+  protected override render() {
+    return html`
+      <vaadin-combo-box
+        .dataProvider="${this.dataProvider}"
+        label="Country"
+        item-label-path="name"
+        item-value-path="id"
+      ></vaadin-combo-box>
+    `;
+  }
+  // end::snippet[]
+}

frontend/demo/component/combobox/react/combo-box-lazy-loading.tsx

@@ -0,0 +1,22 @@
+import { reactExample } from 'Frontend/demo/react-example'; // hidden-source-line
+import React from 'react';
+import { useComboBoxDataProvider } from '@vaadin/hilla-react-crud';
+import { ComboBox } from '@vaadin/react-components/ComboBox.js';
+import { ComboBoxCountryService } from 'Frontend/generated/endpoints';
+
+// tag::snippet[]
+function Example() {
+  // Create a data provider that calls a backend service with a
+  // Spring Data pageable and the current combo box filter
+  const dataProvider = useComboBoxDataProvider(
+    ComboBoxCountryService.list.bind(ComboBoxCountryService)
+  );
+
+  return (
+    <ComboBox dataProvider={dataProvider} label="Country" itemLabelPath="name" itemValuePath="id" />
+  );
+}
+
+// end::snippet[]
+
+export default reactExample(Example); // hidden-source-line

frontend/demo/services/ComboBoxCountryService.ts

@@ -0,0 +1,35 @@
+import { getCountries } from 'Frontend/demo/domain/DataService';
+import { CrudMockService } from 'Frontend/demo/services/CrudService';
+import type Country from 'Frontend/generated/com/vaadin/demo/domain/Country';
+import type PropertyStringFilter from 'Frontend/generated/com/vaadin/hilla/crud/filter/PropertyStringFilter';
+import Matcher from 'Frontend/generated/com/vaadin/hilla/crud/filter/PropertyStringFilter/Matcher';
+import type Pageable from 'Frontend/generated/com/vaadin/hilla/mappedtypes/Pageable';
+
+class ComboBoxCountryService {
+  private mockService?: CrudMockService<Country>;
+
+  async list(pageable: Pageable, filter: string): Promise<Country[]> {
+    await this.initMockService();
+
+    return this.mockService!.list(pageable, this.createFilter(filter));
+  }
+
+  private createFilter(filter: string): PropertyStringFilter {
+    return {
+      '@type': 'propertyString',
+      propertyId: 'name',
+      filterValue: filter,
+      matcher: Matcher.CONTAINS,
+    };
+  }
+
+  private async initMockService() {
+    if (this.mockService) {
+      return;
+    }
+    const data = await getCountries();
+    this.mockService = new CrudMockService(data);
+  }
+}
+
+export default new ComboBoxCountryService();

frontend/demo/services/mocks.ts

@@ -1,10 +1,19 @@
 // This module should export all mock services used in live examples
 // During the build, the `Frontend/generated/endpoints` import is replaced with this module
+import ComboBoxCountryService from 'Frontend/demo/services/ComboBoxCountryService';
 import DashboardService from 'Frontend/demo/services/DashboardService';
 import EmployeeService from 'Frontend/demo/services/EmployeeService';
 import GridPersonService from 'Frontend/demo/services/GridPersonService';
 import LLMChatService from 'Frontend/demo/services/LLMChatService';
 import ProductService from 'Frontend/demo/services/ProductService';
+
 export * from 'Frontend/generated/endpoints.js';
 
-export { DashboardService, EmployeeService, ProductService, GridPersonService, LLMChatService };
+export {
+  DashboardService,
+  EmployeeService,
+  ProductService,
+  GridPersonService,
+  ComboBoxCountryService,
+  LLMChatService,
+};

src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryRepository.java

@@ -0,0 +1,30 @@
+package com.vaadin.demo.component.combobox;
+
+import com.vaadin.demo.domain.Country;
+import com.vaadin.demo.domain.DataService;
+import org.springframework.data.domain.Pageable;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+// hidden-source-line - We don't want to register an actual JPA repository here
+// hidden-source-line - So we put the source code to show in a comment and provide
+// hidden-source-line - a mock implementation that is hidden in the docs
+// tag::snippet[]
+/* // hidden-source-line
+public interface ComboBoxCountryRepository extends JpaRepository<Country, Long> {
+    List<Country> findByNameContainingIgnoreCase(String name, Pageable pageable);
+}
+*/ // hidden-source-line
+// end::snippet[]
+
+@Component // hidden-source-line
+public class ComboBoxCountryRepository { // hidden-source-line
+    List<Country> findByNameContainingIgnoreCase(String name, Pageable pageable) { // hidden-source-line
+        return DataService.getCountries().stream() // hidden-source-line
+                .filter(country -> country.getName().toLowerCase().contains(name.toLowerCase())) // hidden-source-line
+                .skip((long) pageable.getPageNumber() * pageable.getPageSize()) // hidden-source-line
+                .limit(pageable.getPageSize()) // hidden-source-line
+                .toList(); // hidden-source-line
+    } // hidden-source-line
+}// hidden-source-line

src/main/java/com/vaadin/demo/component/combobox/ComboBoxCountryService.java

@@ -0,0 +1,29 @@
+package com.vaadin.demo.component.combobox;
+
+import com.vaadin.demo.domain.Country;
+import com.vaadin.flow.server.auth.AnonymousAllowed;
+import com.vaadin.hilla.BrowserCallable;
+import org.jspecify.annotations.NonNull;
+import org.springframework.data.domain.Pageable;
+
+import java.util.List;
+
+// tag::snippet[]
+// @BrowserCallable and @AnonymousAllowed are only required if you want
+// to use the service from a Hilla view
+@BrowserCallable
+@AnonymousAllowed
+public class ComboBoxCountryService {
+    private final ComboBoxCountryRepository repository;
+
+    public ComboBoxCountryService(ComboBoxCountryRepository repository) {
+        this.repository = repository;
+    }
+
+    public @NonNull List<@NonNull Country> list(Pageable pageable, String filter) {
+        // Implement your data fetching and filtering logic here
+        // For this example, we're using a Spring Data repository
+        return repository.findByNameContainingIgnoreCase(filter, pageable);
+    }
+}
+// end::snippet[]

src/main/java/com/vaadin/demo/component/combobox/ComboBoxLazyLoading.java

@@ -0,0 +1,24 @@
+package com.vaadin.demo.component.combobox;
+
+import com.vaadin.demo.DemoExporter; // hidden-source-line
+import com.vaadin.demo.domain.Country;
+import com.vaadin.flow.component.combobox.ComboBox;
+import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.router.Route;
+
+@Route("combo-box-lazy-loading")
+// tag::snippet[]
+public class ComboBoxLazyLoading extends Div {
+    public ComboBoxLazyLoading(ComboBoxCountryService countryService) {
+        ComboBox<Country> comboBox = new ComboBox<>("Country");
+        comboBox.setItemLabelGenerator(Country::getName);
+        // Connect the combo box to a Spring service that fetches data based
+        // on a Spring Data pageable and the current combo box filter
+        comboBox.setItemsPageable(countryService::list);
+        add(comboBox);
+    }
+
+    public static class Exporter extends DemoExporter<ComboBoxLazyLoading> { // hidden-source-line
+    } // hidden-source-line
+}
+// end::snippet[]