feat(multi-select-combo-box): add itemLabelGenerator property

Allows custom label generation for items in multi-select-combo-box by providing
a function that receives an item and returns a string. This property overrides
itemLabelPath when set.

- Added itemLabelGenerator property to mixin with observer
- Updated chip creation to use generated labels
- Added TypeScript type definition
- Created comprehensive tests
- Added new example in dev page with team member selector

Related to #8333

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: Artur-

dev/multi-select-combo-box.html

@@ -84,8 +84,18 @@
       </vaadin-multi-select-combo-box>
     </div>
 
+    <div style="margin-top: 2rem;">
+      <vaadin-multi-select-combo-box
+        id="team-combo"
+        label="Select team members (with itemLabelGenerator)"
+        clear-button-visible
+      >
+        <vaadin-tooltip slot="tooltip" text="Using itemLabelGenerator to show custom labels"></vaadin-tooltip>
+      </vaadin-multi-select-combo-box>
+    </div>
+
     <script>
-      const comboBox = document.querySelector('vaadin-multi-select-combo-box');
+      const comboBox = document.querySelector('vaadin-multi-select-combo-box:not(#team-combo)');
 
       comboBox.items = [
         'Hydrogen',
@@ -164,6 +174,23 @@
         console.log('change', comboBox.selectedItems);
       });
 
+      // Example with itemLabelGenerator
+      const teamCombo = document.querySelector('#team-combo');
+      teamCombo.items = [
+        { id: 1, name: 'John Doe', email: '[email protected]', role: 'Developer' },
+        { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'Designer' },
+        { id: 3, name: 'Bob Johnson', email: '[email protected]', role: 'Manager' },
+        { id: 4, name: 'Alice Williams', email: '[email protected]', role: 'Developer' },
+        { id: 5, name: 'Charlie Brown', email: '[email protected]', role: 'QA Engineer' },
+        { id: 6, name: 'Diana Davis', email: '[email protected]', role: 'Product Owner' },
+        { id: 7, name: 'Eric Evans', email: '[email protected]', role: 'Developer' },
+        { id: 8, name: 'Fiona Foster', email: '[email protected]', role: 'Designer' }
+      ];
+      teamCombo.itemIdPath = 'id';
+      teamCombo.itemValuePath = 'id';
+      // Generate labels showing name, role and email
+      teamCombo.itemLabelGenerator = (item) => `${item.name} - ${item.role} (${item.email})`;
+
       /*
       comboBox.items = [
         { id: 1, name: 'Hydrogen' },

packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.d.ts

@@ -60,6 +60,8 @@ export declare function MultiSelectComboBoxMixin<TItem, T extends Constructor<HT
   Constructor<ValidateMixinClass> &
   T;
 
+export type MultiSelectComboBoxItemLabelGenerator<TItem> = (item: TItem) => string;
+
 export declare class MultiSelectComboBoxMixinClass<TItem> {
   /**
    * Set to true to auto expand horizontally, causing input field to
@@ -90,6 +92,13 @@ export declare class MultiSelectComboBoxMixinClass<TItem> {
    */
   itemClassNameGenerator: (item: TItem) => string;
 
+  /**
+   * A function to generate the label for each item based on the item.
+   * The function receives the item as an argument and should return a string.
+   * When set, it overrides the `itemLabelPath` property.
+   */
+  itemLabelGenerator: MultiSelectComboBoxItemLabelGenerator<TItem> | undefined;
+
   /**
    * Path for the id of the item, used to detect whether the item is selected.
    * @attr {string} item-id-path
@@ -117,6 +126,8 @@ export declare class MultiSelectComboBoxMixinClass<TItem> {
    *   total: '{count} items selected',
    * }
    * ```
+   * @type {!MultiSelectComboBoxI18n}
+   * @default {English/US}
    */
   i18n: MultiSelectComboBoxI18n;
 
@@ -175,4 +186,4 @@ export declare class MultiSelectComboBoxMixinClass<TItem> {
    * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
    */
   requestContentUpdate(): void;
-}
+}

packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.js

@@ -63,6 +63,18 @@ export const MultiSelectComboBoxMixin = (superClass) =>
           sync: true,
         },
 
+        /**
+         * A function to generate the label for each item based on the item.
+         * The function receives the item as an argument and should return a string.
+         * When set, it overrides the `itemLabelPath` property.
+         *
+         * @type {MultiSelectComboBoxItemLabelGenerator | undefined}
+         */
+        itemLabelGenerator: {
+          type: Function,
+          observer: '_itemLabelGeneratorChanged',
+        },
+
         /**
          * Path for the id of the item, used to detect whether the item is selected.
          * @attr {string} item-id-path
@@ -713,6 +725,14 @@ export const MultiSelectComboBoxMixin = (superClass) =>
       return items.map((item) => this._getItemLabel(item)).join(', ');
     }
 
+    /** @private */
+    _itemLabelGeneratorChanged() {
+      // Update existing chips when the generator changes
+      if (this._hasValue) {
+        this.__updateChips();
+      }
+    }
+
     /** @private */
     _findIndex(item, selectedItems, itemIdPath) {
       if (itemIdPath && item) {

packages/multi-select-combo-box/test/item-label-generator.test.js

@@ -0,0 +1,170 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextFrame, nextRender } from '@vaadin/testing-helpers';
+import '../src/vaadin-multi-select-combo-box.js';
+
+describe('multi-select-combo-box itemLabelGenerator', () => {
+  let comboBox;
+
+  beforeEach(async () => {
+    comboBox = fixtureSync('<vaadin-multi-select-combo-box></vaadin-multi-select-combo-box>');
+    await nextFrame();
+  });
+
+  describe('basic functionality', () => {
+    beforeEach(async () => {
+      comboBox.items = [
+        { label: 'Option 1', value: '1', customProp: 'Custom 1' },
+        { label: 'Option 2', value: '2', customProp: 'Custom 2' },
+        { label: 'Option 3', value: '3', customProp: 'Custom 3' },
+      ];
+      await nextFrame();
+    });
+
+    it('should use item label by default', async () => {
+      comboBox.opened = true;
+      await nextRender();
+
+      const internalComboBox = comboBox.$.comboBox;
+      const items = internalComboBox._scroller.querySelectorAll('vaadin-multi-select-combo-box-item');
+      expect(items[0].textContent.trim()).to.equal('Option 1');
+      expect(items[1].textContent.trim()).to.equal('Option 2');
+      expect(items[2].textContent.trim()).to.equal('Option 3');
+    });
+
+    it('should use itemLabelGenerator when provided', async () => {
+      comboBox.itemLabelGenerator = (item) => `${item.customProp} - ${item.value}`;
+      await nextFrame();
+
+      comboBox.opened = true;
+      await nextRender();
+
+      const internalComboBox = comboBox.$.comboBox;
+      const items = internalComboBox._scroller.querySelectorAll('vaadin-multi-select-combo-box-item');
+      expect(items[0].textContent.trim()).to.equal('Custom 1 - 1');
+      expect(items[1].textContent.trim()).to.equal('Custom 2 - 2');
+      expect(items[2].textContent.trim()).to.equal('Custom 3 - 3');
+    });
+
+    it('should override itemLabelPath when itemLabelGenerator is set', async () => {
+      comboBox.itemLabelPath = 'customProp';
+      comboBox.itemLabelGenerator = (item) => `Generated: ${item.value}`;
+      await nextFrame();
+
+      comboBox.opened = true;
+      await nextRender();
+
+      const internalComboBox = comboBox.$.comboBox;
+      const items = internalComboBox._scroller.querySelectorAll('vaadin-multi-select-combo-box-item');
+      expect(items[0].textContent.trim()).to.equal('Generated: 1');
+    });
+  });
+
+  describe('selected items display', () => {
+    beforeEach(async () => {
+      comboBox.items = [
+        { label: 'Option 1', value: '1', displayName: 'First' },
+        { label: 'Option 2', value: '2', displayName: 'Second' },
+        { label: 'Option 3', value: '3', displayName: 'Third' },
+      ];
+      comboBox.itemLabelPath = 'label';
+      await nextFrame();
+    });
+
+    it('should show generated labels in chips', async () => {
+      comboBox.itemLabelGenerator = (item) => item.displayName;
+      comboBox.selectedItems = [comboBox.items[0], comboBox.items[1]];
+      await nextFrame();
+
+      const chips = Array.from(comboBox.querySelectorAll('vaadin-multi-select-combo-box-chip')).filter(
+        (chip) => !chip.hasAttribute('hidden'),
+      );
+      expect(chips).to.have.lengthOf(2);
+      expect(chips[0].shadowRoot.querySelector('[part="label"]').textContent).to.equal('First');
+      expect(chips[1].shadowRoot.querySelector('[part="label"]').textContent).to.equal('Second');
+    });
+
+    it('should update chip labels when itemLabelGenerator changes', async () => {
+      comboBox.selectedItems = [comboBox.items[0]];
+      await nextFrame();
+
+      const chips = Array.from(comboBox.querySelectorAll('vaadin-multi-select-combo-box-chip')).filter(
+        (chip) => !chip.hasAttribute('hidden') && !chip.overflow,
+      );
+      expect(chips[0].shadowRoot.querySelector('[part="label"]').textContent).to.equal('Option 1');
+
+      comboBox.itemLabelGenerator = (item) => item.displayName;
+      await nextFrame();
+
+      const chipsAfter = Array.from(comboBox.querySelectorAll('vaadin-multi-select-combo-box-chip')).filter(
+        (chip) => !chip.hasAttribute('hidden') && !chip.overflow,
+      );
+      expect(chipsAfter[0].shadowRoot.querySelector('[part="label"]').textContent).to.equal('First');
+    });
+  });
+
+  describe('with complex items', () => {
+    it('should work with nested object properties', async () => {
+      comboBox.items = [
+        { data: { name: 'John', age: 30 }, value: '1' },
+        { data: { name: 'Jane', age: 25 }, value: '2' },
+      ];
+
+      comboBox.itemLabelGenerator = (item) => `${item.data.name} (${item.data.age})`;
+      await nextFrame();
+
+      comboBox.opened = true;
+      await nextRender();
+
+      const internalComboBox = comboBox.$.comboBox;
+      const items = internalComboBox._scroller.querySelectorAll('vaadin-multi-select-combo-box-item');
+      expect(items[0].textContent.trim()).to.equal('John (30)');
+      expect(items[1].textContent.trim()).to.equal('Jane (25)');
+    });
+  });
+
+  describe('filtering', () => {
+    beforeEach(() => {
+      comboBox.items = [
+        { label: 'Apple', value: 'apple', code: 'APL' },
+        { label: 'Banana', value: 'banana', code: 'BNN' },
+        { label: 'Cherry', value: 'cherry', code: 'CHR' },
+      ];
+    });
+
+    it('should filter items based on generated labels', async () => {
+      comboBox.itemLabelGenerator = (item) => `${item.code} - ${item.label}`;
+      await nextFrame();
+
+      comboBox.opened = true;
+      comboBox.filter = 'APL';
+      await nextFrame();
+
+      const items = comboBox.filteredItems;
+      expect(items).to.have.lengthOf(1);
+      expect(items[0].value).to.equal('apple');
+    });
+  });
+
+  describe('readonly mode', () => {
+    it('should show generated labels in chips when readonly', async () => {
+      comboBox.items = [
+        { label: 'Option 1', value: '1', displayName: 'First' },
+        { label: 'Option 2', value: '2', displayName: 'Second' },
+      ];
+      comboBox.itemLabelPath = 'label';
+      comboBox.itemLabelGenerator = (item) => item.displayName;
+      comboBox.selectedItems = [comboBox.items[0], comboBox.items[1]];
+      comboBox.readonly = true;
+      await nextFrame();
+
+      const chips = Array.from(comboBox.querySelectorAll('vaadin-multi-select-combo-box-chip')).filter(
+        (chip) => !chip.hasAttribute('hidden') && !chip.overflow,
+      );
+      expect(chips).to.have.lengthOf(2);
+      expect(chips[0].shadowRoot.querySelector('[part="label"]').textContent).to.equal('First');
+      expect(chips[1].shadowRoot.querySelector('[part="label"]').textContent).to.equal('Second');
+      expect(chips[0].hasAttribute('readonly')).to.be.true;
+      expect(chips[1].hasAttribute('readonly')).to.be.true;
+    });
+  });
+});