feat: timezone config can now be added on a per field basis

docs/fields/date.mdx

@@ -236,7 +236,28 @@ To enable timezone selection on a Date field, set the `timezone` property to `tr
 
 This will add a dropdown to the date picker that allows users to select a timezone. The selected timezone will be saved in the database along with the date in a new column named `date_tz`.
 
-You can customise the available list of timezones in the [global admin config](../admin/overview#timezones).
+You can customise the available list of timezones in the [global admin config](../admin/overview#timezones) or on the field config itself which accepts the following config as well:
+
+| Property             | Description                                                               |
+| -------------------- | ------------------------------------------------------------------------- |
+| `defaultTimezone`    | A value for the default timezone to be set.                               |
+| `supportedTimezones` | An array of supported timezones with label and value object.              |
+| `required`           | If true, the timezone selection will be required even if the date is not. |
+
+```ts
+{
+  name: 'date',
+  type: 'date',
+  timezone: {
+    defaultTimezone: 'America/New_York',
+    supportedTimezones: [
+      { label: 'New York', value: 'America/New_York' },
+      { label: 'Los Angeles', value: 'America/Los_Angeles' },
+      { label: 'London', value: 'Europe/London' },
+    ],
+  },
+}
+```
 
 <Banner type="info">
   **Good to know:**

packages/payload/src/config/types.ts

@@ -439,7 +439,7 @@ export type Timezone = {
 
 type SupportedTimezonesFn = (args: { defaultTimezones: Timezone[] }) => Timezone[]
 
-type TimezonesConfig = {
+export type TimezonesConfig = {
   /**
    * The default timezone to use for the admin panel.
    */

packages/payload/src/exports/shared.ts

@@ -62,30 +62,31 @@ export { isImage } from '../uploads/isImage.js'
 export { appendUploadSelectFields } from '../utilities/appendUploadSelectFields.js'
 export { applyLocaleFiltering } from '../utilities/applyLocaleFiltering.js'
 export { combineWhereConstraints } from '../utilities/combineWhereConstraints.js'
-
 export {
   deepCopyObject,
   deepCopyObjectComplex,
   deepCopyObjectSimple,
   deepCopyObjectSimpleWithoutReactComponents,
 } from '../utilities/deepCopyObject.js'
+
 export {
   deepMerge,
   deepMergeWithCombinedArrays,
   deepMergeWithReactComponents,
   deepMergeWithSourceArrays,
 } from '../utilities/deepMerge.js'
-
 export { extractID } from '../utilities/extractID.js'
 
 export { flattenAllFields } from '../utilities/flattenAllFields.js'
+
 export { flattenTopLevelFields } from '../utilities/flattenTopLevelFields.js'
 export { formatAdminURL } from '../utilities/formatAdminURL.js'
 export { formatLabels, toWords } from '../utilities/formatLabels.js'
-
 export { getBestFitFromSizes } from '../utilities/getBestFitFromSizes.js'
+
 export { getDataByPath } from '../utilities/getDataByPath.js'
 export { getFieldPermissions } from '../utilities/getFieldPermissions.js'
+export { getObjectDotNotation } from '../utilities/getObjectDotNotation.js'
 export { getSafeRedirect } from '../utilities/getSafeRedirect.js'
 
 export { getSelectMode } from '../utilities/getSelectMode.js'

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

@@ -407,9 +407,20 @@ export const sanitizeFields = async ({
     // Insert our field after assignment
     if (field.type === 'date' && field.timezone) {
       const name = field.name + '_tz'
-      const defaultTimezone = config.admin?.timezones?.defaultTimezone
 
-      const supportedTimezones = config.admin?.timezones?.supportedTimezones
+      const defaultTimezone =
+        field.timezone && typeof field.timezone === 'object'
+          ? field.timezone.defaultTimezone
+          : config.admin?.timezones?.defaultTimezone
+
+      const required =
+        field.required ||
+        (field.timezone && typeof field.timezone === 'object' && field.timezone.required)
+
+      const supportedTimezones =
+        field.timezone && typeof field.timezone === 'object' && field.timezone.supportedTimezones
+          ? field.timezone.supportedTimezones
+          : config.admin?.timezones?.supportedTimezones
 
       const options =
         typeof supportedTimezones === 'function'
@@ -422,7 +433,7 @@ export const sanitizeFields = async ({
         name,
         defaultValue: defaultTimezone,
         options,
-        required: field.required,
+        required,
       })
 
       fields.splice(++i, 0, timezoneField)

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

@@ -116,6 +116,8 @@ import type {
   LabelFunction,
   PayloadComponent,
   StaticLabel,
+  Timezone,
+  TimezonesConfig,
 } from '../../config/types.js'
 import type { DBIdentifierName } from '../../database/types.js'
 import type { SanitizedGlobalConfig } from '../../globals/config/types.js'
@@ -723,6 +725,14 @@ export type CheckboxFieldClient = {
 } & FieldBaseClient &
   Pick<CheckboxField, 'type'>
 
+type DateFieldTimezoneConfig = {
+  /**
+   * Make only the timezone required in the admin interface. This means a timezone is always required to be selected.
+   */
+  required?: boolean
+  supportedTimezones?: Timezone[]
+} & Pick<TimezonesConfig, 'defaultTimezone'>
+
 export type DateField = {
   admin?: {
     components?: {
@@ -737,7 +747,7 @@ export type DateField = {
   /**
    * Enable timezone selection in the admin interface.
    */
-  timezone?: true
+  timezone?: DateFieldTimezoneConfig | true
   type: 'date'
   validate?: DateFieldValidation
 } & Omit<FieldBase, 'validate'>

packages/payload/src/utilities/getObjectDotNotation.ts

@@ -1,3 +1,17 @@
+/**
+ *
+ * @deprecated use getObjectDotNotation from `'payload/shared'` instead of `'payload'`
+ *
+ * @example
+ *
+ * ```ts
+ * import { getObjectDotNotation } from 'payload/shared'
+ *
+ * const obj = { a: { b: { c: 42 } } }
+ * const value = getObjectDotNotation<number>(obj, 'a.b.c', 0) // value is 42
+ * const defaultValue = getObjectDotNotation<number>(obj, 'a.b.x', 0) // defaultValue is 0
+ * ```
+ */
 export const getObjectDotNotation = <T>(
   obj: Record<string, unknown>,
   path: string,

packages/ui/src/elements/Table/DefaultCell/fields/Date/index.tsx

@@ -1,25 +1,42 @@
 'use client'
 import type { DateFieldClient, DefaultCellComponentProps } from 'payload'
 
+import { getObjectDotNotation } from 'payload/shared'
 import React from 'react'
 
 import { useConfig } from '../../../../../providers/Config/index.js'
 import { useTranslation } from '../../../../../providers/Translation/index.js'
 import { formatDate } from '../../../../../utilities/formatDocTitle/formatDateTitle.js'
 
-export const DateCell: React.FC<DefaultCellComponentProps<DateFieldClient>> = ({
-  cellData,
-  field: { admin: { date } = {} },
-}) => {
+export const DateCell: React.FC<
+  DefaultCellComponentProps<{ accessor?: string } & DateFieldClient>
+> = (props) => {
+  const {
+    cellData,
+    field: { name, accessor, admin: { date } = {}, timezone: timezoneFromField },
+    rowData,
+  } = props
+
   const {
     config: {
       admin: { dateFormat: dateFormatFromRoot },
     },
   } = useConfig()
+  const { i18n } = useTranslation()
 
-  const dateFormat = date?.displayFormat || dateFormatFromRoot
+  const fieldPath = accessor || name
 
-  const { i18n } = useTranslation()
+  const timezoneFieldName = `${fieldPath}_tz`
+  const timezone =
+    Boolean(timezoneFromField) && rowData
+      ? getObjectDotNotation(rowData, timezoneFieldName, undefined)
+      : undefined
+
+  const dateFormat = date?.displayFormat || dateFormatFromRoot
 
-  return <span>{cellData && formatDate({ date: cellData, i18n, pattern: dateFormat })}</span>
+  return (
+    <span>
+      {Boolean(cellData) && formatDate({ date: cellData, i18n, pattern: dateFormat, timezone })}
+    </span>
+  )
 }

packages/ui/src/elements/TimezonePicker/index.scss

@@ -28,6 +28,7 @@
         background: none;
         border: none;
         padding: 0;
+        padding-left: calc(var(--base) * 0.25);
         min-height: auto !important;
         position: relative;
         box-shadow: unset;

packages/ui/src/elements/TimezonePicker/index.tsx

@@ -18,6 +18,7 @@ export const TimezonePicker: React.FC<Props> = (props) => {
     id,
     onChange: onChangeFromProps,
     options: optionsFromProps,
+    readOnly: readOnlyFromProps,
     required,
     selectedTimezone: selectedTimezoneFromProps,
   } = props
@@ -33,6 +34,8 @@ export const TimezonePicker: React.FC<Props> = (props) => {
     })
   }, [options, selectedTimezoneFromProps])
 
+  const readOnly = Boolean(readOnlyFromProps) || options.length === 1
+
   return (
     <div className="timezone-picker-wrapper">
       <FieldLabel
@@ -43,8 +46,9 @@ export const TimezonePicker: React.FC<Props> = (props) => {
       />
       <ReactSelect
         className="timezone-picker"
+        disabled={readOnly}
         inputId={id}
-        isClearable={true}
+        isClearable={!required}
         isCreatable={false}
         onChange={(val: OptionObject) => {
           if (onChangeFromProps) {

packages/ui/src/elements/TimezonePicker/types.ts

@@ -3,6 +3,7 @@ import type { SelectFieldClient } from 'payload'
 export type Props = {
   id: string
   onChange?: (val: string) => void
+  readOnly?: boolean
   required?: boolean
   selectedTimezone?: string
 } & Pick<SelectFieldClient, 'options'>

packages/ui/src/fields/DateTime/index.tsx

@@ -70,13 +70,23 @@ const DateTimeFieldComponent: DateFieldClientComponent = (props) => {
 
   const timezonePath = path + '_tz'
   const timezoneField = useFormFields(([fields, _]) => fields?.[timezonePath])
-  const supportedTimezones = config.admin.timezones.supportedTimezones
+
+  const supportedTimezones = useMemo(() => {
+    if (timezone && typeof timezone === 'object' && timezone.supportedTimezones) {
+      return timezone.supportedTimezones
+    }
+
+    return config.admin.timezones.supportedTimezones
+  }, [config.admin.timezones.supportedTimezones, timezone])
+
   /**
    * Date appearance doesn't include timestamps,
    * which means we need to pin the time to always 12:00 for the selected date
    */
   const isDateOnly = ['dayOnly', 'default', 'monthOnly'].includes(pickerAppearance)
   const selectedTimezone = timezoneField?.value as string
+  const timezoneRequired =
+    required || (timezone && typeof timezone === 'object' && timezone.required)
 
   // The displayed value should be the original value, adjusted to the user's timezone
   const displayedValue = useMemo(() => {
@@ -192,7 +202,8 @@ const DateTimeFieldComponent: DateFieldClientComponent = (props) => {
             id={`${path}-timezone-picker`}
             onChange={onChangeTimezone}
             options={supportedTimezones}
-            required={required}
+            readOnly={readOnly || disabled}
+            required={timezoneRequired}
             selectedTimezone={selectedTimezone}
           />
         )}