From 063cf232fe99b0df53ae32a286741d3aa0b6df28 Mon Sep 17 00:00:00 2001
From: Andrew Rybka <andrew.rybka@gmail.com>
Date: Sat, 17 Feb 2024 12:17:44 +0100
Subject: [PATCH] Add support for formatType: "utc"

---
 src/channeldef.ts           | 10 +++++-----
 src/compile/format.ts       |  7 +++++--
 test/compile/format.test.ts |  1 +
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/channeldef.ts b/src/channeldef.ts
index 0b8b96f0eb..41037954f8 100644
--- a/src/channeldef.ts
+++ b/src/channeldef.ts
@@ -400,10 +400,10 @@ export interface DatumDef<
 
 export interface FormatMixins {
   /**
-   * When used with the default `"number"` and `"time"` format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.
+   * When used with the default `"number"`, `"time"`, or `"utc"` format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.
    *
    * - If the format type is `"number"` (e.g., for quantitative fields), this is D3's [number format pattern](https://github.com/d3/d3-format#locale_format).
-   * - If the format type is `"time"` (e.g., for temporal fields), this is D3's [time format pattern](https://github.com/d3/d3-time-format#locale_format).
+   * - If the format type is `"time"` or `"utc"` (e.g., for temporal fields), this is D3's [time format pattern](https://github.com/d3/d3-time-format#locale_format).
    *
    * See the [format documentation](https://vega.github.io/vega-lite/docs/format.html) for more examples.
    *
@@ -414,13 +414,13 @@ export interface FormatMixins {
   format?: string | Dict<unknown>;
 
   /**
-   * The format type for labels. One of `"number"`, `"time"`, or a [registered custom format type](https://vega.github.io/vega-lite/docs/config.html#custom-format-type).
+   * The format type for labels. One of `"number"`, `"time"`, `"utc"`, or a [registered custom format type](https://vega.github.io/vega-lite/docs/config.html#custom-format-type).
    *
    * __Default value:__
    * - `"time"` for temporal fields and ordinal and nominal fields with `timeUnit`.
    * - `"number"` for quantitative fields as well as ordinal and nominal fields without `timeUnit`.
    */
-  formatType?: 'number' | 'time' | string;
+  formatType?: 'number' | 'time' | 'utc' | string;
 }
 
 export type StringDatumDef<F extends Field = string> = DatumDef<F> & FormatMixins;
@@ -1338,7 +1338,7 @@ export function channelCompatibility(
  */
 export function isFieldOrDatumDefForTimeFormat(fieldOrDatumDef: FieldDef<string> | DatumDef): boolean {
   const {formatType} = getFormatMixins(fieldOrDatumDef);
-  return formatType === 'time' || (!formatType && isTimeFieldDef(fieldOrDatumDef));
+  return formatType === 'time' || formatType === 'utc' || (!formatType && isTimeFieldDef(fieldOrDatumDef));
 }
 
 /**
diff --git a/src/compile/format.ts b/src/compile/format.ts
index be42af2cdb..7883edfce6 100644
--- a/src/compile/format.ts
+++ b/src/compile/format.ts
@@ -22,7 +22,7 @@ import {TimeUnit} from './../timeunit';
 import {datumDefToExpr} from './mark/encode/valueref';
 
 export function isCustomFormatType(formatType: string) {
-  return formatType && formatType !== 'number' && formatType !== 'time';
+  return formatType && formatType !== 'number' && formatType !== 'time' && formatType !== 'utc';
 }
 
 function customFormatExpr(formatType: string, field: string, format: string | Dict<unknown>) {
@@ -227,7 +227,10 @@ export function guideFormatType(
   fieldOrDatumDef: FieldDef<string> | DatumDef<string>,
   scaleType: ScaleType
 ) {
-  if (formatType && (isSignalRef(formatType) || formatType === 'number' || formatType === 'time')) {
+  if (
+    formatType &&
+    (isSignalRef(formatType) || formatType === 'number' || formatType === 'time' || formatType === 'utc')
+  ) {
     return formatType;
   }
   if (isFieldOrDatumDefForTimeFormat(fieldOrDatumDef) && scaleType !== 'time' && scaleType !== 'utc') {
diff --git a/test/compile/format.test.ts b/test/compile/format.test.ts
index ada7be09f4..853c3ff96e 100644
--- a/test/compile/format.test.ts
+++ b/test/compile/format.test.ts
@@ -356,6 +356,7 @@ describe('Format', () => {
     it('should return existing format type', () => {
       expect(guideFormatType('number', {field: ' foo', type: 'quantitative'}, 'ordinal')).toBe('number');
       expect(guideFormatType('time', {field: ' foo', type: 'quantitative'}, 'ordinal')).toBe('time');
+      expect(guideFormatType('utc', {field: ' foo', type: 'quantitative'}, 'ordinal')).toBe('utc');
     });
 
     it('should return utc for utc time units', () => {