DropDownBox, SelectBox, ColorBox, TagBox: Log fieldTemplate deprecation warning (#30846)

Co-authored-by: Ruslan Farkhutdinov <ruslan.farkhutdinov@devexpress.com>

Author: r-farkhutdinov

apps/demos/testing/known-warnings.js

@@ -1,5 +1,13 @@
+export const dropDownEditorsFieldTemplateWarnings = [
+  'W0001 - dxSelectBox - \'fieldTemplate\'',
+  'W0001 - dxColorBox - \'fieldTemplate\'',
+  'W0001 - dxDropDownBox - \'fieldTemplate\'',
+  'W0001 - dxTagBox - \'fieldTemplate\'',
+];
+
 export const knownWarnings = [
   'W0019 -',
   'W0022 -',
   'W2108 -',
+  ...dropDownEditorsFieldTemplateWarnings,
 ];

packages/devextreme/js/__internal/ui/color_box/m_color_box.ts

@@ -349,6 +349,11 @@ class ColorBox extends DropDownEditor<ColorBoxProperties> {
     return value;
   }
 
+  // eslint-disable-next-line class-methods-use-this
+  _shouldLogFieldTemplateDeprecationWarning(): boolean {
+    return true;
+  }
+
   _clean(): void {
     super._clean();
     delete this._shouldSaveEmptyValue;

packages/devextreme/js/__internal/ui/drop_down_editor/m_drop_down_editor.ts

@@ -56,6 +56,13 @@ const isIOs = devices.current().platform === 'ios';
 
 type HideOnOutsideClickEvent = DxEvent<MouseEvent | PointerEvent | TouchEvent>;
 
+export const DROP_DOWN_EDITOR_DEPRECATED_OPTIONS = {
+  fieldTemplate: {
+    since: '25.2',
+    message: 'Use the \'fieldAddons\' option instead',
+  },
+};
+
 export interface DropDownEditorProperties extends Omit<
   Properties,
   | 'onChange'
@@ -77,6 +84,8 @@ export interface DropDownEditorProperties extends Omit<
 > {
   buttonsLocation?: string;
 
+  fieldTemplate?: string | Element | Function | null;
+
   _onMarkupRendered?: () => void;
 
   onPopupInitialized?: (e: { component: DropDownEditor; popup: Popup }) => void;
@@ -373,18 +382,27 @@ class DropDownEditor<
 
   _cleanFocusState(): void {
     super._cleanFocusState();
+    const { fieldTemplate } = this.option();
 
-    if (this.option('fieldTemplate')) {
+    if (fieldTemplate) {
       this._detachFocusEvents();
     }
   }
 
   _getFieldTemplate() {
-    return this.option('fieldTemplate') && this._getTemplateByOption('fieldTemplate');
+    const { fieldTemplate } = this.option();
+
+    if (!fieldTemplate) {
+      return;
+    }
+
+    return this._getTemplate(fieldTemplate);
   }
 
   _renderMask(): void {
-    if (this.option('fieldTemplate')) {
+    const { fieldTemplate } = this.option();
+
+    if (fieldTemplate) {
       return;
     }
 
@@ -1117,6 +1135,19 @@ class DropDownEditor<
     return super._getSubmitElement();
   }
 
+  // eslint-disable-next-line class-methods-use-this
+  _shouldLogFieldTemplateDeprecationWarning(): boolean {
+    return false;
+  }
+
+  _setDeprecatedOptions(): void {
+    super._setDeprecatedOptions();
+
+    if (this._shouldLogFieldTemplateDeprecationWarning()) {
+      extend(this._deprecatedOptions, DROP_DOWN_EDITOR_DEPRECATED_OPTIONS);
+    }
+  }
+
   _dispose(): void {
     this._detachFocusOutEvents();
     super._dispose();

packages/devextreme/js/__internal/ui/m_drop_down_box.ts

@@ -311,6 +311,11 @@ class DropDownBox<
   // eslint-disable-next-line class-methods-use-this
   _setCollectionWidgetOption(): void {}
 
+  // eslint-disable-next-line class-methods-use-this
+  _shouldLogFieldTemplateDeprecationWarning(): boolean {
+    return true;
+  }
+
   _optionChanged(args) {
     // @ts-expect-error ts-error
     this._dataExpressionOptionChanged(args);

packages/devextreme/js/__internal/ui/m_lookup.ts

@@ -321,9 +321,11 @@ class Lookup extends DropDownList<LookupProperties> {
   }
 
   _renderField() {
+    const { fieldTemplate: fieldTemplateOption } = this.option();
+
     const fieldTemplate = this._getTemplateByOption('fieldTemplate');
 
-    if (fieldTemplate && this.option('fieldTemplate')) {
+    if (fieldTemplate && fieldTemplateOption) {
       this._renderFieldTemplate(fieldTemplate);
       return;
     }

packages/devextreme/js/__internal/ui/m_select_box.ts

@@ -444,9 +444,10 @@ class SelectBox<
   }
 
   _updateField(item): void {
+    const { fieldTemplate: fieldTemplateOption } = this.option();
     const fieldTemplate = this._getTemplateByOption('fieldTemplate');
 
-    if (!(fieldTemplate && this.option('fieldTemplate'))) {
+    if (!(fieldTemplate && fieldTemplateOption)) {
       // @ts-expect-error ts-error
       const text = this._displayGetter(item);
 
@@ -963,6 +964,11 @@ class SelectBox<
     this._caret({ start: valueLength, end: displayValue.length });
   }
 
+  // eslint-disable-next-line class-methods-use-this
+  _shouldLogFieldTemplateDeprecationWarning(): boolean {
+    return true;
+  }
+
   _dispose(): void {
     this._renderInputValueAsync = noop;
     delete this._loadItemDeferred;

packages/devextreme/js/__internal/ui/m_tag_box.ts

@@ -562,7 +562,8 @@ class TagBox<
   }
 
   _renderField(): void {
-    const isDefaultFieldTemplate = !isDefined(this.option('fieldTemplate'));
+    const { fieldTemplate } = this.option();
+    const isDefaultFieldTemplate = !isDefined(fieldTemplate);
 
     this.$element()
       .toggleClass(TAGBOX_DEFAULT_FIELD_TEMPLATE_CLASS, isDefaultFieldTemplate)

packages/devextreme/testing/tests/DevExpress.ui.widgets.editors/dropDownEditors.deprecation.tests.js

@@ -0,0 +1,86 @@
+import 'ui/select_box';
+import 'ui/tag_box';
+import 'ui/color_box';
+import 'ui/drop_down_box';
+import errors from 'core/errors';
+
+const LICENSE_WARNING = 'W0022';
+
+const FIELD_TEMPLATE_WARNING_ARGS = (componentName) => [
+    'W0001',
+    componentName,
+    'fieldTemplate',
+    '25.2',
+    'Use the \'fieldAddons\' option instead',
+];
+
+const FIELD_TEMPLATE_COMPONENTS = [
+    { name: 'dxSelectBox', selector: '#selectBox' },
+    { name: 'dxTagBox', selector: '#tagBox' },
+    { name: 'dxColorBox', selector: '#colorBox' },
+    { name: 'dxDropDownBox', selector: '#dropDownBox' },
+];
+
+QUnit.testStart(() => {
+    const markup =
+        '<div id="selectBox"></div>\
+         <div id="tagBox"></div>\
+         <div id="colorBox"></div>\
+         <div id="dropDownBox"></div>';
+
+    $('#qunit-fixture').html(markup);
+});
+
+QUnit.module('Deprecated fieldTemplate', {
+    beforeEach() {
+        this.errorsSpy = sinon.spy(errors, 'log');
+
+        this.getFilteredWarnings = () =>
+            this.errorsSpy.getCalls().filter(({ args }) => args[0] !== LICENSE_WARNING);
+
+        this.assertWarningIsCorrect = (assert, name) => {
+            const warnings = this.getFilteredWarnings();
+
+            assert.strictEqual(warnings.length, 1, 'only one warning logged');
+            assert.deepEqual(
+                warnings[0].args,
+                FIELD_TEMPLATE_WARNING_ARGS(name),
+                'warning is raised with correct parameters'
+            );
+        };
+    },
+    afterEach() {
+        errors.log.restore();
+    },
+}, () => {
+    const fieldTemplate = () => $('<div>').dxTextBox();
+
+    FIELD_TEMPLATE_COMPONENTS.forEach(({ name, selector }) => {
+        QUnit.test(
+            `${name}: fieldTemplate should raise a deprecation warning on initialization`,
+            function(assert) {
+                $(selector)[name]({ fieldTemplate })[name]('instance');
+                this.assertWarningIsCorrect(assert, name);
+            }
+        );
+
+        QUnit.test(
+            `${name}: fieldTemplate should raise a deprecation warning on option set`,
+            function(assert) {
+                const instance = $(selector)[name]()[name]('instance');
+
+                instance.option({ fieldTemplate });
+
+                this.assertWarningIsCorrect(assert, name);
+            }
+        );
+
+        QUnit.test(`${name}: does not log extra warning on value change call`, function(assert) {
+            const instance = $(selector)[name]({ fieldTemplate })[name]('instance');
+
+            instance.option('value', '');
+
+            this.assertWarningIsCorrect(assert, name);
+        });
+    });
+});