fix: pass timestamp to ticks callback (#10540)

* fix: pass timestamp to ticks callback
* docs: edit labelling page
* docs: additions to the migration guide

docs/axes/labelling.md

@@ -22,7 +22,7 @@ To do this, you need to override the `ticks.callback` method in the axis configu
 
 The method receives 3 arguments:
 
-* `value` - the tick value in the **internal data format** of the associated scale.
+* `value` - the tick value in the **internal data format** of the associated scale. For time scale, it is a timestamp.
 * `index` - the tick index in the ticks array.
 * `ticks` - the array containing all of the [tick objects](../api/interfaces/Tick).
 

docs/migration/v4-migration.md

@@ -11,6 +11,7 @@ A number of changes were made to the configuration options passed to the `Chart`
 #### Specific changes
 
 * The radialLinear grid indexable and scriptable options don't decrease the index of the specified grid line anymore.
+* Ticks callback on time scale now receives timestamp instead of a formatted label.
 
 #### Type changes
 * The order of the `ChartMeta` parameters have been changed from `<Element, DatasetElement, Type>` to `<Type, Element, DatasetElement>`

src/scales/scale.time.js

@@ -232,6 +232,8 @@ export default class TimeScale extends Scale {
        */
       source: 'auto',
 
+      callback: false,
+
       major: {
         enabled: false
       }
@@ -510,6 +512,12 @@ export default class TimeScale extends Scale {
 	 */
   _tickFormatFunction(time, index, ticks, format) {
     const options = this.options;
+    const formatter = options.ticks.callback;
+
+    if (formatter) {
+      return call(formatter, [time, index, ticks], this);
+    }
+
     const formats = options.time.displayFormats;
     const unit = this._unit;
     const majorUnit = this._majorUnit;
@@ -517,9 +525,8 @@ export default class TimeScale extends Scale {
     const majorFormat = majorUnit && formats[majorUnit];
     const tick = ticks[index];
     const major = majorUnit && majorFormat && tick && tick.major;
-    const label = this._adapter.format(time, format || (major ? majorFormat : minorFormat));
+
-    const formatter = options.ticks.callback;
+    return this._adapter.format(time, format || (major ? majorFormat : minorFormat));
-    return formatter ? call(formatter, [label, index, ticks], this) : label;
   }
 
   /**

test/specs/scale.time.tests.js

@@ -73,6 +73,7 @@ describe('Time scale tests', function() {
       },
       ticks: {
         source: 'auto',
+        callback: false,
         major: {
           enabled: false
         }
@@ -353,8 +354,8 @@ describe('Time scale tests', function() {
                 }
               },
               ticks: {
-                callback: function(value) {
+                callback: function(_, i) {
-                  return '<' + value + '>';
+                  return '<' + i + '>';
                 }
               }
             }
@@ -368,21 +369,21 @@ describe('Time scale tests', function() {
       var labels = getLabels(this.scale);
 
       expect(labels.length).toEqual(21);
-      expect(labels[0]).toEqual('<8:00:00>');
+      expect(labels[0]).toEqual('<0>');
-      expect(labels[labels.length - 1]).toEqual('<8:01:00>');
+      expect(labels[labels.length - 1]).toEqual('<60>');
     });
 
     it('should update ticks.callback correctly', function() {
       var chart = this.chart;
-      chart.options.scales.x.ticks.callback = function(value) {
+      chart.options.scales.x.ticks.callback = function(_, i) {
-        return '{' + value + '}';
+        return '{' + i + '}';
       };
       chart.update();
 
       var labels = getLabels(this.scale);
       expect(labels.length).toEqual(21);
-      expect(labels[0]).toEqual('{8:00:00}');
+      expect(labels[0]).toEqual('{0}');
-      expect(labels[labels.length - 1]).toEqual('{8:01:00}');
+      expect(labels[labels.length - 1]).toEqual('{60}');
     });
   });
 
@@ -1260,4 +1261,33 @@ describe('Time scale tests', function() {
 
     expect(chartOptions).toEqual(chart.options);
   });
+
+  it('should pass timestamp to ticks callback', () => {
+    let callbackValue;
+    window.acquireChart({
+      type: 'line',
+      data: {
+        datasets: [{
+          xAxisID: 'x',
+          data: [0, 0]
+        }],
+        labels: ['2015-01-01T20:00:00', '2015-01-01T20:01:00']
+      },
+      options: {
+        scales: {
+          x: {
+            type: 'time',
+            ticks: {
+              callback(value) {
+                callbackValue = value;
+                return value;
+              }
+            }
+          }
+        }
+      }
+    });
+
+    expect(typeof callbackValue).toBe('number');
+  });
 });