feat: support partial i18n in time picker (#9141)

Author: sissbruecker

packages/time-picker/src/vaadin-time-picker-mixin.d.ts

@@ -10,6 +10,7 @@ import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
 import type { KeyboardMixinClass } from '@vaadin/a11y-base/src/keyboard-mixin.js';
 import type { ComboBoxBaseMixinClass } from '@vaadin/combo-box/src/vaadin-combo-box-base-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 { 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';
@@ -22,8 +23,9 @@ import type { ValidateMixinClass } from '@vaadin/field-base/src/validate-mixin.j
 import type { TimePickerTime } from './vaadin-time-picker-helper.js';
 
 export interface TimePickerI18n {
-  parseTime(time: string): TimePickerTime | undefined;
-  formatTime(time: TimePickerTime | undefined): string;
+  parseTime?(time: string): TimePickerTime | undefined;
+
+  formatTime?(time: TimePickerTime | undefined): string;
 }
 
 /**
@@ -38,6 +40,7 @@ export declare function TimePickerMixin<T extends Constructor<HTMLElement>>(
   Constructor<DisabledMixinClass> &
   Constructor<FieldMixinClass> &
   Constructor<FocusMixinClass> &
+  Constructor<I18nMixinClass<TimePickerI18n>> &
   Constructor<InputConstraintsMixinClass> &
   Constructor<InputControlMixinClass> &
   Constructor<InputMixinClass> &
@@ -99,9 +102,9 @@ export declare class TimePickerMixinClass {
   step: number | null | undefined;
 
   /**
-   * 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 both the
+   * time parsing and formatting functions.
    *
    * The object has the following JSON structure:
    *
@@ -124,8 +127,8 @@ export declare class TimePickerMixinClass {
    * }
    * ```
    *
-   * Both `formatTime` and `parseTime` need to be implemented
-   * to ensure the component works properly.
+   * NOTE: `formatTime` and `parseTime` must be implemented in a
+   * compatible manner to ensure the component works properly.
    */
   i18n: TimePickerI18n;
 }

packages/time-picker/src/vaadin-time-picker-mixin.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { ComboBoxBaseMixin } from '@vaadin/combo-box/src/vaadin-combo-box-base-mixin.js';
+import { I18nMixin } from '@vaadin/component-base/src/i18n-mixin.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';
@@ -24,11 +25,15 @@ const MAX_ALLOWED_TIME = '23:59:59.999';
  *
  * @polymerMixin
  * @mixes ComboBoxBaseMixin
+ * @mixes I18nMixin
  * @mixes InputControlMixin
  * @mixes PatternMixin
  */
 export const TimePickerMixin = (superClass) =>
-  class TimePickerMixinClass extends PatternMixin(ComboBoxBaseMixin(InputControlMixin(superClass))) {
+  class TimePickerMixinClass extends I18nMixin(
+    timePickerI18nDefaults,
+    PatternMixin(ComboBoxBaseMixin(InputControlMixin(superClass))),
+  ) {
     static get properties() {
       return {
         /**
@@ -98,43 +103,6 @@ export const TimePickerMixin = (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:
-         *
-         * ```
-         * {
-         *   // A function to format given `Object` as
-         *   // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
-         *   formatTime: (time) => {
-         *     // returns a string representation of the given
-         *     // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats
-         *   },
-         *
-         *   // A function to parse the given text to an `Object` in the format
-         *   // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.
-         *   // Must properly parse (at least) text
-         *   // formatted by `formatTime`.
-         *   parseTime: text => {
-         *     // Parses a string in object/string that can be formatted by`formatTime`.
-         *   }
-         * }
-         * ```
-         *
-         * Both `formatTime` and `parseTime` need to be implemented
-         * to ensure the component works properly.
-         *
-         * @type {!TimePickerI18n}
-         */
-        i18n: {
-          type: Object,
-          sync: true,
-          value: () => ({ ...timePickerI18nDefaults }),
-        },
-
         /** @private */
         _comboBoxValue: {
           type: String,
@@ -154,7 +122,7 @@ export const TimePickerMixin = (superClass) =>
         '_openedOrItemsChanged(opened, _dropdownItems)',
         '_updateScroller(opened, _dropdownItems, _focusedIndex, _theme)',
         '__updateAriaAttributes(_dropdownItems, opened, inputElement)',
-        '__updateDropdownItems(i18n, min, max, step)',
+        '__updateDropdownItems(__effectiveI18n, min, max, step)',
       ];
     }
 
@@ -180,14 +148,53 @@ export const TimePickerMixin = (superClass) =>
       return this.$.clearButton;
     }
 
+    /**
+     * The object used to localize this component. To change the default
+     * localization, replace this with an object that provides both the
+     * time parsing and formatting functions.
+     *
+     * The object has the following JSON structure:
+     *
+     * ```
+     * {
+     *   // A function to format given `Object` as
+     *   // time string. Object is in the format `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`
+     *   formatTime: (time) => {
+     *     // returns a string representation of the given
+     *     // object in `hh` / 'hh:mm' / 'hh:mm:ss' / 'hh:mm:ss.fff' - formats
+     *   },
+     *
+     *   // A function to parse the given text to an `Object` in the format
+     *   // `{ hours: ..., minutes: ..., seconds: ..., milliseconds: ... }`.
+     *   // Must properly parse (at least) text
+     *   // formatted by `formatTime`.
+     *   parseTime: text => {
+     *     // Parses a string in object/string that can be formatted by`formatTime`.
+     *   }
+     * }
+     * ```
+     *
+     * NOTE: `formatTime` and `parseTime` must be implemented in a
+     * compatible manner to ensure the component works properly.
+     *
+     * @return {!TimePickerI18n}
+     */
+    get i18n() {
+      return super.i18n;
+    }
+
+    set i18n(value) {
+      super.i18n = value;
+    }
+
     /**
      * The input element's value when it cannot be parsed as a time, and an empty string otherwise.
      *
      * @private
      * @return {string}
      */
     get __unparsableValue() {
-      if (this._inputElementValue && !this.i18n.parseTime(this._inputElementValue)) {
+      if (this._inputElementValue && !this.__effectiveI18n.parseTime(this._inputElementValue)) {
         return this._inputElementValue;
       }
 
@@ -245,8 +252,8 @@ export const TimePickerMixin = (superClass) =>
     checkValidity() {
       return !!(
         this.inputElement.checkValidity() &&
-        (!this.value || this._timeAllowed(this.i18n.parseTime(this.value))) &&
-        (!this._comboBoxValue || this.i18n.parseTime(this._comboBoxValue))
+        (!this.value || this._timeAllowed(this.__effectiveI18n.parseTime(this.value))) &&
+        (!this._comboBoxValue || this.__effectiveI18n.parseTime(this._comboBoxValue))
       );
     }
 
@@ -411,7 +418,7 @@ export const TimePickerMixin = (superClass) =>
       // observer where the value can be parsed again, so we set
       // this flag to ensure it does not alter the value.
       this.__useMemo = true;
-      this._comboBoxValue = this.i18n.formatTime(objWithStep);
+      this._comboBoxValue = this.__effectiveI18n.formatTime(objWithStep);
       this.__useMemo = false;
 
       this.__commitValueChange();
@@ -508,7 +515,7 @@ export const TimePickerMixin = (superClass) =>
     }
 
     /** @private */
-    __updateDropdownItems(i18n, min, max, step) {
+    __updateDropdownItems(effectiveI18n, min, max, step) {
       const minTimeObj = validateTime(parseISOTime(min || MIN_ALLOWED_TIME), step);
       const minSec = this.__getSec(minTimeObj);
 
@@ -524,7 +531,7 @@ export const TimePickerMixin = (superClass) =>
       }
 
       if (this.value) {
-        this._comboBoxValue = i18n.formatTime(i18n.parseTime(this.value));
+        this._comboBoxValue = effectiveI18n.formatTime(effectiveI18n.parseTime(this.value));
       }
     }
 
@@ -560,7 +567,7 @@ export const TimePickerMixin = (superClass) =>
       while (time + step >= minSec && time + step <= maxSec) {
         const timeObj = validateTime(this.__addStep(time * 1000, step), step);
         time += step;
-        const formatted = this.i18n.formatTime(timeObj);
+        const formatted = this.__effectiveI18n.formatTime(timeObj);
         generatedList.push({ label: formatted, value: formatted });
       }
 
@@ -606,8 +613,8 @@ export const TimePickerMixin = (superClass) =>
         return;
       }
 
-      const parsedObj = this.__useMemo ? this.__memoValue : this.i18n.parseTime(value);
-      const newValue = this.i18n.formatTime(parsedObj) || '';
+      const parsedObj = this.__useMemo ? this.__memoValue : this.__effectiveI18n.parseTime(value);
+      const newValue = this.__effectiveI18n.formatTime(parsedObj) || '';
 
       if (parsedObj) {
         if (value !== newValue) {
@@ -644,7 +651,7 @@ export const TimePickerMixin = (superClass) =>
 
     /** @private */
     __updateInputValue(obj) {
-      const timeString = this.i18n.formatTime(validateTime(obj, this.step)) || '';
+      const timeString = this.__effectiveI18n.formatTime(validateTime(obj, this.step)) || '';
       this._inputElementValue = timeString;
       this._comboBoxValue = timeString;
     }
@@ -657,8 +664,8 @@ export const TimePickerMixin = (superClass) =>
      * @protected
      */
     _timeAllowed(time) {
-      const parsedMin = this.i18n.parseTime(this.min || MIN_ALLOWED_TIME);
-      const parsedMax = this.i18n.parseTime(this.max || MAX_ALLOWED_TIME);
+      const parsedMin = this.__effectiveI18n.parseTime(this.min || MIN_ALLOWED_TIME);
+      const parsedMax = this.__effectiveI18n.parseTime(this.max || MAX_ALLOWED_TIME);
 
       return (
         (!this.__getMsec(parsedMin) || this.__getMsec(time) >= this.__getMsec(parsedMin)) &&

packages/time-picker/test/keyboard-navigation.test.js

@@ -108,15 +108,17 @@ describe('keyboard navigation', () => {
 
     describe('with custom parser and formatter', () => {
       beforeEach(() => {
-        timePicker.i18n.parseTime = (text) => {
-          const parts = text.split('.');
-          return {
-            hours: parts[0],
-            minutes: parts[1],
-          };
-        };
-        timePicker.i18n.formatTime = (time) => {
-          return `${time.hours}.${time.minutes}`;
+        timePicker.i18n = {
+          parseTime(text) {
+            const parts = text.split('.');
+            return {
+              hours: parts[0],
+              minutes: parts[1],
+            };
+          },
+          formatTime(time) {
+            return `${time.hours}.${time.minutes}`;
+          },
         };
       });
 

packages/time-picker/test/time-picker.test.js

@@ -352,7 +352,7 @@ describe('time-picker', () => {
 
   describe('custom functions', () => {
     it('should use custom parser if that exists', () => {
-      timePicker.i18n = { ...timePicker.i18n, parseTime: sinon.stub().returns({ hours: 12, minutes: 0, seconds: 0 }) };
+      timePicker.i18n = { parseTime: sinon.stub().returns({ hours: 12, minutes: 0, seconds: 0 }) };
       timePicker.value = '12';
       expect(timePicker.i18n.parseTime.args[0][0]).to.be.equal('12:00');
       expect(timePicker.value).to.be.equal('12:00');
@@ -387,6 +387,14 @@ describe('time-picker', () => {
       expect(inputElement.value).to.equal('1200');
       expect(timePicker.value).to.equal('12:00');
     });
+
+    it('should fallback to default functions if none are provided', () => {
+      timePicker.i18n = {};
+
+      timePicker.value = '12:00';
+      expect(inputElement.value).to.equal('12:00');
+      expect(timePicker.value).to.equal('12:00');
+    });
   });
 
   describe('helper text', () => {

packages/time-picker/test/typings/time-picker.types.ts

@@ -5,6 +5,7 @@ import type {
 } from '@vaadin/combo-box/src/vaadin-combo-box-item-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 { ClearButtonMixinClass } from '@vaadin/field-base/src/clear-button-mixin.js';
 import type { InputControlMixinClass } from '@vaadin/field-base/src/input-control-mixin.js';
 import type { PatternMixinClass } from '@vaadin/field-base/src/pattern-mixin.js';
@@ -14,6 +15,7 @@ import type { TimePickerItem } from '../../src/vaadin-time-picker-item.js';
 import type {
   TimePicker,
   TimePickerChangeEvent,
+  TimePickerI18n,
   TimePickerInvalidChangedEvent,
   TimePickerOpenedChangedEvent,
   TimePickerValidatedEvent,
@@ -26,6 +28,7 @@ const timePicker = document.createElement('vaadin-time-picker');
 
 // Mixins
 assertType<ElementMixinClass>(timePicker);
+assertType<I18nMixinClass<TimePickerI18n>>(timePicker);
 assertType<InputControlMixinClass>(timePicker);
 assertType<ClearButtonMixinClass>(timePicker);
 assertType<PatternMixinClass>(timePicker);
@@ -66,6 +69,9 @@ timePicker.addEventListener('validated', (event) => {
   assertType<boolean>(event.detail.valid);
 });
 
+// I18n
+assertType<TimePickerI18n>({});
+
 // Item
 const item = document.createElement('vaadin-time-picker-item');
 assertType<TimePickerItem>(item);