Stepper: implement Step.hint property (#29361)

Author: EugeniyKiyashko

packages/devextreme/js/__internal/ui/collection/m_item.ts

@@ -41,14 +41,14 @@ const forcibleWatcher = <T>(
   };
 };
 
-export interface ItemExtraOption<TProperties, T = boolean> {
+export interface ItemExtraOption<TProperties> {
   owner: Record<string, unknown>;
-  fieldGetter: (
+  fieldGetter: <TT>(
     field: keyof TProperties
-  ) => (rawData: TProperties | undefined) => T;
-  watchMethod: () => (
+  ) => (rawData: TProperties | undefined) => TT;
+  watchMethod: <TT>() => (
     fn: () => void,
-    callback: (value: T) => void
+    callback: (value: TT) => void
   ) => () => void;
 }
 
@@ -93,18 +93,18 @@ class CollectionItem<
     this._startWatcher('visible', this._renderVisible.bind(this));
   }
 
-  _startWatcher(
+  _startWatcher<T = boolean>(
     field: keyof TProperties,
     render: (
-      value: boolean | undefined,
-      oldValue: boolean | undefined,
+      value: T | undefined,
+      oldValue: T | undefined,
     ) => void,
   ): void {
     const rawData = this._rawData;
-    const exprGetter = this._options.fieldGetter(field);
+    const exprGetter = this._options.fieldGetter<T>(field);
 
-    const watcher = forcibleWatcher<boolean>(
-      this._options.watchMethod(),
+    const watcher = forcibleWatcher<T>(
+      this._options.watchMethod<T>(),
       () => exprGetter(rawData),
       (value, oldValue) => {
         this._dirty = true;

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

@@ -48,6 +48,8 @@ export interface StepperProperties extends Properties {
   loopItemFocus?: boolean;
 
   selectionRequired?: boolean;
+
+  hintExpr?: (data: Item) => string | undefined;
 }
 
 class Stepper extends CollectionWidgetAsync<StepperProperties> {
@@ -69,6 +71,7 @@ class Stepper extends CollectionWidgetAsync<StepperProperties> {
       focusStateEnabled: true,
       loopItemFocus: false,
       selectionRequired: true,
+      hintExpr(data): string | undefined { return data ? data.hint : undefined; },
     };
   }
 
@@ -366,6 +369,9 @@ class Stepper extends CollectionWidgetAsync<StepperProperties> {
         break;
       case 'linear':
         break;
+      case 'hintExpr':
+        this._invalidate();
+        break;
       default:
         super._optionChanged(args);
     }

packages/devextreme/js/__internal/ui/stepper/stepper_item.ts

@@ -7,6 +7,18 @@ export const STEP_VALID_ICON = 'check';
 export const STEP_INVALID_ICON = 'errorcircle';
 
 class StepperItem extends CollectionWidgetItem<Item> {
+  _renderWatchers(): void {
+    super._renderWatchers();
+
+    this._startWatcher<string>('hint', (value) => {
+      this._renderHint(value);
+    });
+  }
+
+  _renderHint(hint: string | undefined): void {
+    this._$element.attr('title', hint ?? null);
+  }
+
   updateInvalidClass(isValid: boolean | undefined): void {
     this._$element.toggleClass(STEP_INVALID_CLASS, isValid !== undefined && !isValid);
   }

packages/devextreme/testing/tests/DevExpress.ui.widgets/stepper.markup.tests.js

@@ -332,5 +332,61 @@ QUnit.module('Step.isValid', moduleConfig, () => {
             assert.strictEqual($stepText.children().eq(0).hasClass(`${ICON_CLASS}-${expectedIcon}`), true);
         });
     });
+});
+
+QUnit.module('Step.hint', moduleConfig, () => {
+    QUnit.test('Step should not have a title attribute if the hint is not defined', function(assert) {
+        this.reinit({
+            items: [{}, { hint: undefined }, { hint: null }]
+        });
 
+        const items = this.getItems();
+        assert.strictEqual(items.eq(0).attr('title'), undefined, 'Title is not set when hint is missing');
+        assert.strictEqual(items.eq(1).attr('title'), undefined, 'Title is not set when hint is undefined');
+        assert.strictEqual(items.eq(2).attr('title'), undefined, 'Title is not set when hint is null');
+    });
+
+    QUnit.test('Step should have a title attribute with the correct value when hint is defined', function(assert) {
+        this.reinit({
+            items: [{ hint: '' }, { hint: 'hint text' }, { hint: 0 }, { hint: true }, { hint: NaN }]
+        });
+
+        const items = this.getItems();
+        assert.strictEqual(items.eq(0).attr('title'), '', 'Title is correctly set for an empty string hint');
+        assert.strictEqual(items.eq(1).attr('title'), 'hint text', 'Title is correctly set for a text hint');
+        assert.strictEqual(items.eq(2).attr('title'), '0', 'Title is correctly set for a numeric hint');
+        assert.strictEqual(items.eq(3).attr('title'), 'true', 'Title is correctly set when hint is boolean');
+        assert.strictEqual(items.eq(4).attr('title'), 'NaN', 'Title is correctly set when hint is NaN');
+    });
+
+    QUnit.test('Step title should update when the hint option value changes at runtime', function(assert) {
+        this.reinit({
+            items: [{ hint: 'Hint value' }]
+        });
+
+        const items = this.getItems();
+        assert.strictEqual(items.eq(0).attr('title'), 'Hint value', 'Initial title is set correctly');
+
+        this.instance.option('items[0].hint', 'New hint value');
+
+        assert.strictEqual(items.eq(0).attr('title'), 'New hint value', 'Title is updated when hint changes');
+    });
+
+    QUnit.test('Step title should be removed when hint is set to undefined or null', function(assert) {
+        this.reinit({
+            items: [{ hint: 'Initial hint' }]
+        });
+
+        const items = this.getItems();
+        assert.strictEqual(items.eq(0).attr('title'), 'Initial hint', 'Initial title is set correctly');
+
+        this.instance.option('items[0].hint', undefined);
+        assert.strictEqual(items.eq(0).attr('title'), undefined, 'Title is removed when hint is set to undefined');
+
+        this.instance.option('items[0].hint', 'New hint');
+        assert.strictEqual(items.eq(0).attr('title'), 'New hint', 'Title is set correctly after hint update');
+
+        this.instance.option('items[0].hint', null);
+        assert.strictEqual(items.eq(0).attr('title'), undefined, 'Title is removed when hint is set to null');
+    });
 });