feat: support partial i18n in multi-select-combo-box (#10147)

sissbruecker · web-flow · commit 367be618547d · 2025-09-10T09:45:39.000+03:00
diff --git a/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.d.ts b/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.d.ts
@@ -13,6 +13,7 @@ import type { ComboBoxBaseMixinClass } from '@vaadin/combo-box/src/vaadin-combo-
 import type { ComboBoxDataProviderMixinClass } from '@vaadin/combo-box/src/vaadin-combo-box-data-provider-mixin.js';
 import type { ComboBoxItemsMixinClass } from '@vaadin/combo-box/src/vaadin-combo-box-items-mixin.js';
 import type { DelegateStateMixinClass } from '@vaadin/component-base/src/delegate-state-mixin.js';
+import type { I18nMixinClass } from '@vaadin/component-base/src/i18n-mixin.js';
 import type { ResizeMixinClass } from '@vaadin/component-base/src/resize-mixin.js';
 import type { SlotStylesMixinClass } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import type { ClearButtonMixinClass } from '@vaadin/field-base/src/clear-button-mixin.js';
@@ -31,11 +32,11 @@ export type MultiSelectComboBoxRenderer<TItem> = (
 ) => void;
 
 export interface MultiSelectComboBoxI18n {
-  cleared: string;
-  focused: string;
-  selected: string;
-  deselected: string;
-  total: string;
+  cleared?: string;
+  focused?: string;
+  selected?: string;
+  deselected?: string;
+  total?: string;
 }
 
 export declare function MultiSelectComboBoxMixin<TItem, T extends Constructor<HTMLElement>>(
@@ -49,6 +50,7 @@ export declare function MultiSelectComboBoxMixin<TItem, T extends Constructor<HT
   Constructor<DisabledMixinClass> &
   Constructor<FieldMixinClass> &
   Constructor<FocusMixinClass> &
+  Constructor<I18nMixinClass<MultiSelectComboBoxI18n>> &
   Constructor<InputConstraintsMixinClass> &
   Constructor<InputControlMixinClass> &
   Constructor<InputMixinClass> &
@@ -97,9 +99,9 @@ export declare class MultiSelectComboBoxMixinClass<TItem> {
   itemIdPath: string;
 
   /**
-   * The object used to localize this component.
-   * To change the default localization, replace the entire
-   * _i18n_ object or just the property you want to modify.
+   * The object used to localize this component. To change the default
+   * localization, replace this with an object that provides all properties, or
+   * just the individual properties you want to change.
    *
    * The object has the following JSON structure and default values:
    * ```js
diff --git a/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.js b/packages/multi-select-combo-box/src/vaadin-multi-select-combo-box-mixin.js
@@ -7,23 +7,34 @@ import { announce } from '@vaadin/a11y-base/src/announce.js';
 import { ComboBoxDataProviderMixin } from '@vaadin/combo-box/src/vaadin-combo-box-data-provider-mixin.js';
 import { ComboBoxItemsMixin } from '@vaadin/combo-box/src/vaadin-combo-box-items-mixin.js';
 import { ComboBoxPlaceholder } from '@vaadin/combo-box/src/vaadin-combo-box-placeholder.js';
+import { I18nMixin } from '@vaadin/component-base/src/i18n-mixin.js';
 import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
 import { TooltipController } from '@vaadin/component-base/src/tooltip-controller.js';
 import { InputControlMixin } from '@vaadin/field-base/src/input-control-mixin.js';
 import { InputController } from '@vaadin/field-base/src/input-controller.js';
 import { LabelledInputController } from '@vaadin/field-base/src/labelled-input-controller.js';
 
+const DEFAULT_I18N = {
+  cleared: 'Selection cleared',
+  focused: 'focused. Press Backspace to remove',
+  selected: 'added to selection',
+  deselected: 'removed from selection',
+  total: '{count} items selected',
+};
+
 /**
  * @polymerMixin
  * @mixes ComboBoxDataProviderMixin
  * @mixes ComboBoxItemsMixin
+ * @mixes I18nMixin
  * @mixes InputControlMixin
  * @mixes ResizeMixin
  */
 export const MultiSelectComboBoxMixin = (superClass) =>
-  class MultiSelectComboBoxMixinClass extends ComboBoxDataProviderMixin(
-    ComboBoxItemsMixin(InputControlMixin(ResizeMixin(superClass))),
+  class MultiSelectComboBoxMixinClass extends I18nMixin(
+    DEFAULT_I18N,
+    ComboBoxDataProviderMixin(ComboBoxItemsMixin(InputControlMixin(ResizeMixin(superClass)))),
   ) {
     static get properties() {
       return {
@@ -72,43 +83,6 @@ export const MultiSelectComboBoxMixin = (superClass) =>
           sync: true,
         },
 
-        /**
-         * The object used to localize this component.
-         * To change the default localization, replace the entire
-         * _i18n_ object or just the property you want to modify.
-         *
-         * The object has the following JSON structure and default values:
-         * ```js
-         * {
-         *   // Screen reader announcement on clear button click.
-         *   cleared: 'Selection cleared',
-         *   // Screen reader announcement when a chip is focused.
-         *   focused: ' focused. Press Backspace to remove',
-         *   // Screen reader announcement when item is selected.
-         *   selected: 'added to selection',
-         *   // Screen reader announcement when item is deselected.
-         *   deselected: 'removed from selection',
-         *   // Screen reader announcement of the selected items count.
-         *   // {count} is replaced with the actual count of items.
-         *   total: '{count} items selected',
-         * }
-         * ```
-         * @type {!MultiSelectComboBoxI18n}
-         * @default {English/US}
-         */
-        i18n: {
-          type: Object,
-          value: () => {
-            return {
-              cleared: 'Selection cleared',
-              focused: 'focused. Press Backspace to remove',
-              selected: 'added to selection',
-              deselected: 'removed from selection',
-              total: '{count} items selected',
-            };
-          },
-        },
-
         /**
          * When true, filter string isn't cleared after selecting an item.
          */
@@ -244,6 +218,37 @@ export const MultiSelectComboBoxMixin = (superClass) =>
       ];
     }
 
+    /**
+     * The object used to localize this component. To change the default
+     * localization, replace this with an object that provides all properties, or
+     * just the individual properties you want to change.
+     *
+     * The object has the following JSON structure and default values:
+     * ```js
+     * {
+     *   // Screen reader announcement on clear button click.
+     *   cleared: 'Selection cleared',
+     *   // Screen reader announcement when a chip is focused.
+     *   focused: ' focused. Press Backspace to remove',
+     *   // Screen reader announcement when item is selected.
+     *   selected: 'added to selection',
+     *   // Screen reader announcement when item is deselected.
+     *   deselected: 'removed from selection',
+     *   // Screen reader announcement of the selected items count.
+     *   // {count} is replaced with the actual count of items.
+     *   total: '{count} items selected',
+     * }
+     * ```
+     * @return {!MultiSelectComboBoxI18n}
+     */
+    get i18n() {
+      return super.i18n;
+    }
+
+    set i18n(value) {
+      super.i18n = value;
+    }
+
     /** @protected */
     get slotStyles() {
       const tag = this.localName;
@@ -384,7 +389,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
     clear() {
       this.__updateSelection([]);
 
-      announce(this.i18n.cleared);
+      announce(this.__effectiveI18n.cleared);
     }
 
     /**
@@ -750,8 +755,8 @@ export const MultiSelectComboBoxMixin = (superClass) =>
     /** @private */
     __announceItem(itemLabel, isSelected, itemCount) {
       const state = isSelected ? 'selected' : 'deselected';
-      const total = this.i18n.total.replace('{count}', itemCount || 0);
-      announce(`${itemLabel} ${this.i18n[state]} ${total}`);
+      const total = this.__effectiveI18n.total.replace('{count}', itemCount || 0);
+      announce(`${itemLabel} ${this.__effectiveI18n[state]} ${total}`);
     }
 
     /** @private */
@@ -1218,7 +1223,7 @@ export const MultiSelectComboBoxMixin = (superClass) =>
         if (focusedIndex > -1) {
           const item = chips[focusedIndex].item;
           const itemLabel = this._getItemLabel(item);
-          announce(`${itemLabel} ${this.i18n.focused}`);
+          announce(`${itemLabel} ${this.__effectiveI18n.focused}`);
         }
       }
     }
diff --git a/packages/multi-select-combo-box/test/i18n.test.js b/packages/multi-select-combo-box/test/i18n.test.js
@@ -0,0 +1,78 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextRender } from '@vaadin/testing-helpers';
+import sinon from 'sinon';
+import '../src/vaadin-multi-select-combo-box.js';
+
+describe('i18n', () => {
+  describe('announcements', () => {
+    let comboBox, region, clock;
+
+    before(() => {
+      region = document.querySelector('[aria-live]');
+    });
+
+    beforeEach(async () => {
+      comboBox = fixtureSync(`<vaadin-multi-select-combo-box></vaadin-multi-select-combo-box>`);
+      comboBox.items = ['Apple', 'Banana', 'Lemon', 'Orange'];
+      await nextRender();
+      clock = sinon.useFakeTimers({ shouldClearNativeTimers: true });
+    });
+
+    afterEach(() => {
+      clock.restore();
+    });
+
+    it('should use default i18n messages', () => {
+      comboBox.__selectItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple added to selection 1 items selected');
+
+      comboBox.__removeItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple removed from selection 0 items selected');
+
+      comboBox.clear();
+      clock.tick(150);
+      expect(region.textContent).to.equal('Selection cleared');
+    });
+
+    it('should use custom i18n messages', () => {
+      comboBox.i18n = {
+        cleared: 'Custom cleared message',
+        selected: 'custom selected',
+        deselected: 'custom deselected',
+        total: 'Custom total: {count} selected items',
+      };
+
+      comboBox.__selectItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple custom selected Custom total: 1 selected items');
+
+      comboBox.__removeItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple custom deselected Custom total: 0 selected items');
+
+      comboBox.clear();
+      clock.tick(150);
+      expect(region.textContent).to.equal('Custom cleared message');
+    });
+
+    it('should fall back to defaults when custom messages are missing', () => {
+      comboBox.i18n = {
+        selected: 'custom selected',
+      };
+
+      comboBox.__selectItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple custom selected 1 items selected');
+
+      comboBox.__removeItem('Apple');
+      clock.tick(150);
+      expect(region.textContent).to.equal('Apple removed from selection 0 items selected');
+
+      comboBox.clear();
+      clock.tick(150);
+      expect(region.textContent).to.equal('Selection cleared');
+    });
+  });
+});
diff --git a/packages/multi-select-combo-box/test/typings/multi-select-combo-box.types.ts b/packages/multi-select-combo-box/test/typings/multi-select-combo-box.types.ts
@@ -12,6 +12,7 @@ import type { ComboBoxItemsMixinClass } from '@vaadin/combo-box/src/vaadin-combo
 import type { DelegateStateMixinClass } from '@vaadin/component-base/src/delegate-state-mixin.js';
 import type { DirMixinClass } from '@vaadin/component-base/src/dir-mixin.js';
 import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
+import type { I18nMixinClass } from '@vaadin/component-base/src/i18n-mixin.js';
 import type { SlotStylesMixinClass } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import type { ClearButtonMixinClass } from '@vaadin/field-base/src/clear-button-mixin.js';
 import type { FieldMixinClass } from '@vaadin/field-base/src/field-mixin.js';
@@ -120,6 +121,7 @@ assertType<DelegateStateMixinClass>(narrowedComboBox);
 assertType<DisabledMixinClass>(narrowedComboBox);
 assertType<FieldMixinClass>(narrowedComboBox);
 assertType<FocusMixinClass>(narrowedComboBox);
+assertType<I18nMixinClass<MultiSelectComboBoxI18n>>(narrowedComboBox);
 assertType<InputConstraintsMixinClass>(narrowedComboBox);
 assertType<InputControlMixinClass>(narrowedComboBox);
 assertType<ClearButtonMixinClass>(narrowedComboBox);
@@ -150,3 +152,7 @@ assertType<() => void>(narrowedItem.requestContentUpdate);
 assertType<ComboBoxItemMixinClass<TestComboBoxItem, MultiSelectComboBox>>(narrowedItem);
 assertType<DirMixinClass>(narrowedItem);
 assertType<ThemableMixinClass>(narrowedItem);
+
+// I18n
+assertType<MultiSelectComboBoxI18n>({});
+assertType<MultiSelectComboBoxI18n>({ cleared: 'Cleared' });
