feat: add support for UTC timezone in date fields (#14586)

Adds support for 'UTC' as a value for timezones. This was not previously
supported because we run a check on the values used against the runtime
of Intl API.

```ts
import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    timezones: {
      supportedTimezones: [
        {
          label: 'UTC',
          value: 'UTC',
        },
        // ...other timezones
      ],
      defaultTimezone: 'UTC',
    },
  },
})
```

Also fixes an issue when having only one timezone making it selected by
default.

Author: paulpopus

docs/admin/overview.mdx

@@ -286,12 +286,14 @@ Users in the Admin Panel have the ability to choose between light mode and dark
 
 The `admin.timezones` configuration allows you to configure timezone settings for the Admin Panel. You can customise the available list of timezones and in the future configure the default timezone for the Admin Panel and for all users.
 
+Dates in Payload are always stored in UTC in the database. The timezone settings in the Admin Panel affect only how dates are displayed to editors to help ensure consistency for multi-region editorial teams.
+
 The following options are available:
 
-| Option               | Description                                                                                                     |
-| -------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `supportedTimezones` | An array of label/value options for selectable timezones where the value is the IANA name eg. `America/Detroit` |
-| `defaultTimezone`    | The `value` of the default selected timezone. eg. `America/Los_Angeles`                                         |
+| Option               | Description                                                                                                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `supportedTimezones` | An array of label/value options for selectable timezones where the value is the IANA name eg. `America/Detroit`. Also supports a function that is given the defaultTimezones list. |
+| `defaultTimezone`    | The `value` of the default selected timezone. eg. `America/Los_Angeles`                                                                                                            |
 
 We validate the supported timezones array by checking the value against the list of IANA timezones supported via the Intl API, specifically `Intl.supportedValuesOf('timeZone')`.
 
@@ -330,6 +332,63 @@ const config = buildConfig({
 })
 ```
 
+### Extending supported timezones
+
+For `supportedTimezones` we also support using a function that is given the defaultTimezones list. This allows you to easily extend the default list of timezones rather than replacing it completely.
+
+```ts
+import { buildConfig } from 'payload'
+
+const config = buildConfig({
+  // ...
+  admin: {
+    timezones: {
+      supportedTimezones: ({ defaultTimezones }) => [
+        ...defaultTimezones, // list provided by Payload
+        {
+          label: 'Europe/Dublin',
+          value: 'Europe/Dublin',
+        },
+        {
+          label: 'Europe/Amsterdam',
+          value: 'Europe/Amsterdam',
+        },
+        {
+          label: 'Europe/Bucharest',
+          value: 'Europe/Bucharest',
+        },
+      ],
+      defaultTimezone: 'Europe/Amsterdam',
+    },
+  },
+})
+```
+
+### Using a UTC timezone
+
+In some situations you may want the displayed date and time to match exactly what's being stored in the database where we always store values in UTC. You can do this by adding UTC as a valid timezone option.
+Using a UTC timezone means that an editor inputing for example '1pm' will always see '1pm' and the stored value will be '13:00:00Z'.
+
+```ts
+import { buildConfig } from 'payload'
+
+const config = buildConfig({
+  // ...
+  admin: {
+    timezones: {
+      supportedTimezones: [
+        {
+          label: 'UTC',
+          value: 'UTC',
+        },
+        // ...other timezones
+      ],
+      defaultTimezone: 'UTC',
+    },
+  },
+})
+```
+
 ## Toast
 
 The `admin.toast` configuration allows you to customize the handling of toast messages within the Admin Panel, such as increasing the duration they are displayed and limiting the number of visible toasts at once.

packages/payload/src/config/sanitize.ts

@@ -94,7 +94,7 @@ const sanitizeAdminConfig = (configToSanitize: Config): Partial<SanitizedConfig>
 
   // We're casting here because it's already been sanitised above but TS still thinks it could be a function
   ;(sanitizedConfig.admin!.timezones.supportedTimezones as Timezone[]).forEach((timezone) => {
-    if (!_internalSupportedTimezones.includes(timezone.value)) {
+    if (timezone.value !== 'UTC' && !_internalSupportedTimezones.includes(timezone.value)) {
       throw new InvalidConfiguration(
         `Timezone ${timezone.value} is not supported by the current runtime via the Intl API.`,
       )

packages/payload/src/fields/config/sanitize.ts

@@ -408,7 +408,7 @@ export const sanitizeFields = async ({
     if (field.type === 'date' && field.timezone) {
       const name = field.name + '_tz'
 
-      const defaultTimezone =
+      let defaultTimezone =
         field.timezone && typeof field.timezone === 'object'
           ? field.timezone.defaultTimezone
           : config.admin?.timezones?.defaultTimezone
@@ -427,6 +427,10 @@ export const sanitizeFields = async ({
           ? supportedTimezones({ defaultTimezones })
           : supportedTimezones
 
+      if (options && options.length === 1 && options[0]?.value) {
+        defaultTimezone = options[0].value
+      }
+
       // Need to set the options here manually so that any database enums are generated correctly
       // The UI component will import the options from the config
       const timezoneField = baseTimezoneField({

test/fields/baseConfig.ts

@@ -148,6 +148,7 @@ export const baseConfig: Partial<Config> = {
       supportedTimezones: ({ defaultTimezones }) => [
         ...defaultTimezones,
         { label: '(GMT-6) Monterrey, Nuevo Leon', value: 'America/Monterrey' },
+        { label: 'Custom UTC', value: 'UTC' },
       ],
       defaultTimezone: 'America/Monterrey',
     },

test/fields/collections/Date/e2e.spec.ts

@@ -682,6 +682,48 @@ const createTimezoneContextTests = (contextName: string, timezoneId: string) =>
       }).toPass({ timeout: 10000, intervals: [100] })
     })
 
+    test('creates the expected UTC value when the selected timezone is UTC', async () => {
+      const expectedDateInput = 'Jan 1, 2025 6:00 PM'
+      const expectedUTCValue = '2025-01-01T18:00:00.000Z'
+
+      await page.goto(url.create)
+
+      const dateField = page.locator('#field-default input')
+      await dateField.fill('01/01/2025')
+
+      const dateTimeLocator = page.locator(
+        '#field-dayAndTimeWithTimezone .react-datepicker-wrapper input',
+      )
+
+      const dropdownControlSelector = `#field-dayAndTimeWithTimezone .rs__control`
+      const timezoneOptionSelector = `#field-dayAndTimeWithTimezone .rs__menu .rs__option:has-text("Custom UTC")`
+
+      await page.click(dropdownControlSelector)
+      await page.click(timezoneOptionSelector)
+      await dateTimeLocator.fill(expectedDateInput)
+
+      await saveDocAndAssert(page)
+
+      const docID = page.url().split('/').pop()
+
+      // eslint-disable-next-line payload/no-flaky-assertions
+      expect(docID).toBeTruthy()
+
+      const {
+        docs: [existingDoc],
+      } = await payload.find({
+        collection: dateFieldsSlug,
+        where: {
+          id: {
+            equals: docID,
+          },
+        },
+      })
+
+      // eslint-disable-next-line payload/no-flaky-assertions
+      expect(existingDoc?.dayAndTimeWithTimezone).toEqual(expectedUTCValue)
+    })
+
     test('creates the expected UTC value when the selected timezone is Paris - no daylight savings', async () => {
       const expectedDateInput = 'Jan 1, 2025 6:00 PM'
       const expectedUTCValue = '2025-01-01T17:00:00.000Z'

test/fields/payload-types.ts

@@ -60,7 +60,8 @@ export type SupportedTimezones =
   | 'Pacific/Noumea'
   | 'Pacific/Auckland'
   | 'Pacific/Fiji'
-  | 'America/Monterrey';
+  | 'America/Monterrey'
+  | 'UTC';
 
 export interface Config {
   auth: {
@@ -106,6 +107,7 @@ export interface Config {
     'uploads-multi-poly': UploadsMultiPoly;
     'uploads-restricted': UploadsRestricted;
     'ui-fields': UiField;
+    'payload-kv': PayloadKv;
     'payload-locked-documents': PayloadLockedDocument;
     'payload-preferences': PayloadPreference;
     'payload-migrations': PayloadMigration;
@@ -146,6 +148,7 @@ export interface Config {
     'uploads-multi-poly': UploadsMultiPolySelect<false> | UploadsMultiPolySelect<true>;
     'uploads-restricted': UploadsRestrictedSelect<false> | UploadsRestrictedSelect<true>;
     'ui-fields': UiFieldsSelect<false> | UiFieldsSelect<true>;
+    'payload-kv': PayloadKvSelect<false> | PayloadKvSelect<true>;
     'payload-locked-documents': PayloadLockedDocumentsSelect<false> | PayloadLockedDocumentsSelect<true>;
     'payload-preferences': PayloadPreferencesSelect<false> | PayloadPreferencesSelect<true>;
     'payload-migrations': PayloadMigrationsSelect<false> | PayloadMigrationsSelect<true>;
@@ -1796,6 +1799,23 @@ export interface UiField {
   updatedAt: string;
   createdAt: string;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "payload-kv".
+ */
+export interface PayloadKv {
+  id: string;
+  key: string;
+  data:
+    | {
+        [k: string]: unknown;
+      }
+    | unknown[]
+    | string
+    | number
+    | boolean
+    | null;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "payload-locked-documents".
@@ -3477,6 +3497,14 @@ export interface UiFieldsSelect<T extends boolean = true> {
   updatedAt?: T;
   createdAt?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "payload-kv_select".
+ */
+export interface PayloadKvSelect<T extends boolean = true> {
+  key?: T;
+  data?: T;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "payload-locked-documents_select".