feat: add normalizedNumberFormat for stack: "normalize" tooltips

build/vega-lite-schema.json

@@ -7643,8 +7643,16 @@
           "$ref": "#/definitions/MarkConfig",
           "description": "Mark Config"
         },
+        "normalizedNumberFormat": {
+          "description": "If normalizedNumberFormatType is not specified, D3 number format for axis labels, text marks, and tooltips of normalized stacked fields (fields with `stack: \"normalize\"`). For example `\"s\"` for SI units. Use [D3's number format pattern](https://github.com/d3/d3-format#locale_format).\n\nIf `config.normalizedNumberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function. __Default value:__ `.2%`",
+          "type": "string"
+        },
+        "normalizedNumberFormatType": {
+          "description": "[Custom format type](https://vega.github.io/vega-lite/docs/config.html#custom-format-type) for `config.normalizedNumberFormat`.\n\n__Default value:__ `undefined` -- This is equilvalent to call D3-format, which is exposed as [`format` in Vega-Expression](https://vega.github.io/vega/docs/expressions/#format). __Note:__ You must also set `customFormatTypes` to `true` to use this feature.",
+          "type": "string"
+        },
         "numberFormat": {
-          "description": "If numberFormatType is not specified, D3 Number format for guide labels and text marks. For example `\"s\"` for SI units. Use [D3's number format pattern](https://github.com/d3/d3-format#locale_format).\n\nIf `config.numberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function.",
+          "description": "If numberFormatType is not specified, D3 number format for guide labels, text marks, and tooltips of non-normalized fields (fields *without* `stack: \"normalize\"`). For example `\"s\"` for SI units. Use [D3's number format pattern](https://github.com/d3/d3-format#locale_format).\n\nIf `config.numberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function.",
           "type": "string"
         },
         "numberFormatType": {

examples/compiled/stacked_area_normalize.vg.json

@@ -72,7 +72,7 @@
               "orient": {"value": "vertical"},
               "fill": {"scale": "color", "field": "series"},
               "description": {
-                "signal": "\"date (year-month): \" + (timeFormat(datum[\"yearmonth_date\"], '%Y')) + \"; Sum of count: \" + (format(datum[\"sum_count_end\"]-datum[\"sum_count_start\"], \"\")) + \"; series: \" + (isValid(datum[\"series\"]) ? datum[\"series\"] : \"\"+datum[\"series\"])"
+                "signal": "\"date (year-month): \" + (timeFormat(datum[\"yearmonth_date\"], '%Y')) + \"; Sum of count: \" + (format(datum[\"sum_count_end\"]-datum[\"sum_count_start\"], \".2%\")) + \"; series: \" + (isValid(datum[\"series\"]) ? datum[\"series\"] : \"\"+datum[\"series\"])"
               },
               "x": {"scale": "x", "field": "yearmonth_date"},
               "y": {"scale": "y", "field": "sum_count_end"},

examples/compiled/stacked_bar_h_normalized_labeled.vg.json

@@ -72,7 +72,7 @@
           "fill": {"scale": "color", "field": "gender"},
           "ariaRoleDescription": {"value": "bar"},
           "description": {
-            "signal": "\"population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \"\")) + \"; age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
+            "signal": "\"population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \".2%\")) + \"; age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
           },
           "x": {"scale": "x", "field": "sum_people_end"},
           "x2": {"scale": "x", "field": "sum_people_start"},
@@ -91,7 +91,7 @@
           "opacity": {"value": 0.9},
           "fill": {"value": "white"},
           "description": {
-            "signal": "\"population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \"\")) + \"; age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
+            "signal": "\"population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \".2%\")) + \"; age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
           },
           "x": {
             "signal": "scale(\"x\", 0.5 * datum[\"sum_people_start\"] + 0.5 * datum[\"sum_people_end\"])"

examples/compiled/stacked_bar_normalize.vg.json

@@ -56,7 +56,7 @@
           "fill": {"scale": "color", "field": "gender"},
           "ariaRoleDescription": {"value": "bar"},
           "description": {
-            "signal": "\"age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \"\")) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
+            "signal": "\"age: \" + (isValid(datum[\"age\"]) ? datum[\"age\"] : \"\"+datum[\"age\"]) + \"; population: \" + (format(datum[\"sum_people_end\"]-datum[\"sum_people_start\"], \".2%\")) + \"; gender: \" + (isValid(datum[\"gender\"]) ? datum[\"gender\"] : \"\"+datum[\"gender\"])"
           },
           "x": {"scale": "x", "field": "age"},
           "width": {"scale": "x", "band": 1},

src/compile/axis/encode.ts

@@ -1,5 +1,5 @@
 import {getSecondaryRangeChannel, PositionScaleChannel} from '../../channel';
-import {channelDefType, getFieldOrDatumDef} from '../../channeldef';
+import {channelDefType, getFieldOrDatumDef, isPositionFieldOrDatumDef} from '../../channeldef';
 import {formatCustomType, isCustomFormatType} from '../format';
 import {UnitModel} from '../unit';
 
@@ -39,6 +39,25 @@ export function labels(model: UnitModel, channel: PositionScaleChannel, specifie
       }),
       ...specifiedLabelsSpec
     };
+  } else if (
+    format === undefined &&
+    formatType === undefined &&
+    config.customFormatTypes &&
+    config.normalizedNumberFormatType &&
+    isPositionFieldOrDatumDef(fieldOrDatumDef) &&
+    fieldOrDatumDef.stack === 'normalize' &&
+    channelDefType(fieldOrDatumDef) === 'quantitative'
+  ) {
+    return {
+      text: formatCustomType({
+        fieldOrDatumDef,
+        field: 'datum.value',
+        format: config.normalizedNumberFormat,
+        formatType: config.normalizedNumberFormatType,
+        config
+      }),
+      ...specifiedLabelsSpec
+    };
   }
 
   return specifiedLabelsSpec;

src/compile/format.ts

@@ -7,6 +7,7 @@ import {
   FieldDef,
   isFieldDef,
   isFieldOrDatumDefForTimeFormat,
+  isPositionFieldOrDatumDef,
   isScaleFieldDef,
   vgField
 } from '../channeldef';
@@ -58,6 +59,23 @@ export function formatSignalRef({
   const field = fieldToFormat(fieldOrDatumDef, expr, normalizeStack);
   const type = channelDefType(fieldOrDatumDef);
 
+  if (
+    normalizeStack &&
+    type === 'quantitative' &&
+    format === undefined &&
+    formatType === undefined &&
+    config.customFormatTypes &&
+    config.normalizedNumberFormatType
+  ) {
+    return formatCustomType({
+      fieldOrDatumDef,
+      format: config.normalizedNumberFormat,
+      formatType: config.normalizedNumberFormatType,
+      expr,
+      config
+    });
+  }
+
   if (
     type === 'quantitative' &&
     format === undefined &&
@@ -74,6 +92,23 @@ export function formatSignalRef({
     });
   }
 
+  if (
+    normalizeStack &&
+    type === 'quantitative' &&
+    format === undefined &&
+    formatType === undefined &&
+    config.customFormatTypes &&
+    config.normalizedNumberFormatType
+  ) {
+    return formatCustomType({
+      fieldOrDatumDef,
+      format: config.normalizedNumberFormat,
+      formatType: config.normalizedNumberFormatType,
+      expr,
+      config
+    });
+  }
+
   if (isFieldOrDatumDefForTimeFormat(fieldOrDatumDef)) {
     const signal = timeFormatExpression(
       field,
@@ -85,7 +120,7 @@ export function formatSignalRef({
     return signal ? {signal} : undefined;
   }
 
-  format = numberFormat(type, format, config);
+  format = numberFormat(type, format, config, normalizeStack);
   if (isFieldDef(fieldOrDatumDef) && isBinning(fieldOrDatumDef.bin)) {
     const endField = vgField(fieldOrDatumDef, {expr, binSuffix: 'end'});
     return {
@@ -163,6 +198,15 @@ export function guideFormat(
     return undefined; // handled in encode block
   } else if (format === undefined && formatType === undefined && config.numberFormatType && config.customFormatTypes) {
     return undefined; // handled in encode block
+  } else if (
+    format === undefined &&
+    formatType === undefined &&
+    config.normalizedNumberFormatType &&
+    config.customFormatTypes &&
+    isPositionFieldOrDatumDef(fieldOrDatumDef) &&
+    fieldOrDatumDef.stack === 'normalize'
+  ) {
+    return undefined; // handled in encode block
   }
 
   if (isFieldOrDatumDefForTimeFormat(fieldOrDatumDef)) {
@@ -191,15 +235,20 @@ export function guideFormatType(
 /**
  * Returns number format for a fieldDef.
  */
-export function numberFormat(type: Type, specifiedFormat: string | Dict<unknown>, config: Config) {
+export function numberFormat(
+  type: Type,
+  specifiedFormat: string | Dict<unknown>,
+  config: Config,
+  normalizedStack?: boolean
+) {
   // Specified format in axis/legend has higher precedence than fieldDef.format
   if (isString(specifiedFormat)) {
     return specifiedFormat;
   }
 
   if (type === QUANTITATIVE) {
     // we only apply the default if the field is quantitative
-    return config.numberFormat;
+    return normalizedStack ? config.normalizedNumberFormat : config.numberFormat;
   }
   return undefined;
 }
@@ -243,7 +292,6 @@ export function binFormatExpression(
   if (format === undefined && formatType === undefined && config.customFormatTypes && config.numberFormatType) {
     return binFormatExpression(startField, endField, config.numberFormat, config.numberFormatType, config);
   }
-
   const start = binNumberFormatExpr(startField, format, formatType, config);
   const end = binNumberFormatExpr(endField, format, formatType, config);
   return `${fieldValidPredicate(startField, false)} ? "null" : ${start} + "${BIN_RANGE_DELIMITER}" + ${end}`;

src/config.ts

@@ -146,7 +146,7 @@ export interface VLOnlyConfig<ES extends ExprRef | SignalRef> {
 
   /**
    * If numberFormatType is not specified,
-   * D3 Number format for guide labels and text marks. For example `"s"` for SI units.
+   * D3 number format for guide labels, text marks, and tooltips of non-normalized fields (fields *without* `stack: "normalize"`). For example `"s"` for SI units.
    * Use [D3's number format pattern](https://github.com/d3/d3-format#locale_format).
    *
    * If `config.numberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function.
@@ -162,6 +162,25 @@ export interface VLOnlyConfig<ES extends ExprRef | SignalRef> {
    */
   numberFormatType?: string;
 
+  /**
+   * If normalizedNumberFormatType is not specified,
+   * D3 number format for axis labels, text marks, and tooltips of normalized stacked fields (fields with `stack: "normalize"`). For example `"s"` for SI units.
+   * Use [D3's number format pattern](https://github.com/d3/d3-format#locale_format).
+   *
+   * If `config.normalizedNumberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function.
+   * __Default value:__ `.2%`
+   */
+  normalizedNumberFormat?: string;
+
+  /**
+   * [Custom format type](https://vega.github.io/vega-lite/docs/config.html#custom-format-type)
+   * for `config.normalizedNumberFormat`.
+   *
+   * __Default value:__ `undefined` -- This is equilvalent to call D3-format, which is exposed as [`format` in Vega-Expression](https://vega.github.io/vega/docs/expressions/#format).
+   * __Note:__ You must also set `customFormatTypes` to `true` to use this feature.
+   */
+  normalizedNumberFormatType?: string;
+
   /**
    * Default time format for raw time values (without time units) in text marks, legend labels and header labels.
    *
@@ -330,7 +349,9 @@ export const defaultConfig: Config<SignalRef> = {
   title: {},
 
   facet: {spacing: DEFAULT_SPACING},
-  concat: {spacing: DEFAULT_SPACING}
+  concat: {spacing: DEFAULT_SPACING},
+
+  normalizedNumberFormat: '.2%'
 };
 
 // Tableau10 color palette, copied from `vegaScale.scheme('tableau10')`
@@ -593,6 +614,8 @@ const VL_ONLY_CONFIG_PROPERTIES: (keyof Config)[] = [
   'concat',
   'numberFormat',
   'numberFormatType',
+  'normalizedNumberFormat',
+  'normalizedNumberFormatType',
   'timeFormat',
   'countTitle',
   'header',

test/compile/axis/encode.test.ts

@@ -61,5 +61,21 @@ describe('compile/axis/encode', () => {
       const labels = encode.labels(model, 'x', {});
       expect(labels.text.signal).toBe('customNumberFormat(datum.value, "abc")');
     });
+
+    it('applies custom format type from a normalized stack', () => {
+      const model = parseUnitModelWithScale({
+        mark: 'point',
+        encoding: {
+          x: {field: 'a', type: 'quantitative', stack: 'normalize'}
+        },
+        config: {
+          customFormatTypes: true,
+          normalizedNumberFormat: 'abc',
+          normalizedNumberFormatType: 'customNumberFormat'
+        }
+      });
+      const labels = encode.labels(model, 'x', {});
+      expect(labels.text.signal).toBe('customNumberFormat(datum.value, "abc")');
+    });
   });
 });

test/compile/format.test.ts

@@ -1,4 +1,4 @@
-import {vgField} from '../../src/channeldef';
+import {PositionDatumDef, vgField} from '../../src/channeldef';
 import {
   formatSignalRef,
   guideFormat,
@@ -82,6 +82,10 @@ describe('Format', () => {
       expect(numberFormat(QUANTITATIVE, undefined, {numberFormat: 'd'})).toBe('d');
     });
 
+    it('should use normalized number format for quantitative scale with stack: "normalize"', () => {
+      expect(numberFormat(QUANTITATIVE, undefined, {numberFormat: 'd', normalizedNumberFormat: 'c'}, true)).toBe('c');
+    });
+
     it('should use number format for ordinal and nominal data but don not use config', () => {
       for (const type of [ORDINAL, NOMINAL]) {
         expect(numberFormat(type, undefined, {numberFormat: 'd'})).toBeUndefined();
@@ -178,6 +182,66 @@ describe('Format', () => {
         signal: 'customFormatter(200, "abc")'
       });
     });
+
+    it('should use a custom formatter datumDef if config.normalizedNumberFormatType is present and stack is normalized', () => {
+      expect(
+        formatSignalRef({
+          fieldOrDatumDef: {datum: 200, type: 'quantitative'},
+          format: undefined,
+          formatType: undefined,
+          expr: 'parent',
+          normalizeStack: true,
+          config: {
+            normalizedNumberFormat: 'abc',
+            normalizedNumberFormatType: 'customFormatter',
+            customFormatTypes: true
+          }
+        })
+      ).toEqual({
+        signal: 'customFormatter(200, "abc")'
+      });
+    });
+
+    it('should prefer normalizedNumberFormat over numberFormat when stack is normalized', () => {
+      expect(
+        formatSignalRef({
+          fieldOrDatumDef: {datum: 200, type: 'quantitative'},
+          format: undefined,
+          formatType: undefined,
+          expr: 'parent',
+          normalizeStack: true,
+          config: {
+            numberFormat: 'def',
+            numberFormatType: 'customFormatter2',
+            normalizedNumberFormat: 'abc',
+            normalizedNumberFormatType: 'customFormatter',
+            customFormatTypes: true
+          }
+        })
+      ).toEqual({
+        signal: 'customFormatter(200, "abc")'
+      });
+    });
+
+    it('should prefer numberFormat over normalizedNumberFormat when stack is not normalized', () => {
+      expect(
+        formatSignalRef({
+          fieldOrDatumDef: {datum: 200, type: 'quantitative'},
+          format: undefined,
+          formatType: undefined,
+          expr: 'parent',
+          config: {
+            numberFormat: 'def',
+            numberFormatType: 'customFormatter2',
+            normalizedNumberFormat: 'abc',
+            normalizedNumberFormatType: 'customFormatter',
+            customFormatTypes: true
+          }
+        })
+      ).toEqual({
+        signal: 'customFormatter2(200, "def")'
+      });
+    });
   });
 
   describe('guideFormat', () => {
@@ -196,6 +260,18 @@ describe('Format', () => {
       );
       expect(format).toBeUndefined();
     });
+
+    it('returns undefined for custom normalizedNumberFormatType in the config', () => {
+      const format = guideFormat(
+        {datum: 200, type: 'quantitative', stack: 'normalize'} as PositionDatumDef<string>,
+        'quantitative',
+        undefined,
+        undefined,
+        {normalizedNumberFormat: 'abc', normalizedNumberFormatType: 'customFormatter', customFormatTypes: true},
+        false
+      );
+      expect(format).toBeUndefined();
+    });
   });
 
   describe('guideFormatType()', () => {