@nixxie-cms/fields-timezone 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @nixxie-cms/fields-timezone
+
+A timezone field for Nixxie CMS. Stores a validated IANA timezone id (e.g. `Asia/Karachi`).
+Validation uses `Intl.supportedValuesOf('timeZone')` when the runtime provides it (cached),
+falling back to probing `Intl.DateTimeFormat` otherwise.
+
+```ts
+import { timezone } from '@nixxie-cms/fields-timezone'
+
+fields: {
+  tz: timezone({ validation: { isRequired: true } }),
+}
+```
+
+Also exports:
+
+- `listTimezones()` — all IANA ids known to the runtime, or a curated list of ~30 common
+  zones as a fallback
+- `currentOffset(tz)` — the zone's current UTC offset, e.g. `"UTC+05:00"` (DST-aware, so it
+  varies across the year; on very old runtimes the short style may yield an abbreviation
+  like `"PST"`, returned as-is)

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,28 @@
+import type { TextFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+/**
+ * All IANA timezone ids known to the runtime (via `Intl.supportedValuesOf`), or a curated list
+ * of ~30 common zones on runtimes without it.
+ */
+export declare function listTimezones(): string[];
+/**
+ * The current UTC offset of a timezone, e.g. `currentOffset('Asia/Karachi')` → `"UTC+05:00"`.
+ * Computed via `Intl.DateTimeFormat` with `timeZoneName: 'longOffset'`; on older runtimes the
+ * `'short'` style is used instead and may yield an abbreviation (e.g. `"PST"`), which is
+ * returned as-is. Throws a `RangeError` for unknown timezones. Note the offset is "current" —
+ * DST-observing zones return different values across the year.
+ */
+export declare function currentOffset(tz: string): string;
+export type TimezoneFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<TextFieldConfig<CollectionTypeInfo>, 'validation'> & {
+    validation?: {
+        /** Reject saving when no value is present. */
+        isRequired?: boolean;
+    };
+};
+/**
+ * A timezone field storing an IANA timezone id (e.g. `Asia/Karachi`). Built on the core `text`
+ * field; values are validated against `Intl.supportedValuesOf('timeZone')` when available,
+ * otherwise by probing `Intl.DateTimeFormat`. Empty/null values pass through untouched.
+ */
+export declare function timezone<CollectionTypeInfo extends BaseCollectionTypeInfo>(config?: TimezoneFieldConfig<CollectionTypeInfo>): FieldTypeFunc<CollectionTypeInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAmEnF;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAGxC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAmBhD;AAED,MAAM,MAAM,mBAAmB,CAAC,kBAAkB,SAAS,sBAAsB,IAAI,IAAI,CACvF,eAAe,CAAC,kBAAkB,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE;QACX,8CAA8C;QAC9C,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;CACF,CAAA;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,kBAAkB,SAAS,sBAAsB,EACxE,MAAM,GAAE,mBAAmB,CAAC,kBAAkB,CAAM,GACnD,aAAa,CAAC,kBAAkB,CAAC,CA2BnC"}

package/dist/nixxie-cms-fields-timezone.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1maWVsZHMtdGltZXpvbmUuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/nixxie-cms-fields-timezone.cjs.js

@@ -0,0 +1,120 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+/** ~30 widely used zones, used only on runtimes without `Intl.supportedValuesOf`. */
+const FALLBACK_TIMEZONES = ['UTC', 'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Europe/Madrid', 'Europe/Rome', 'Europe/Moscow', 'Europe/Istanbul', 'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'America/Toronto', 'America/Mexico_City', 'America/Bogota', 'America/Sao_Paulo', 'America/Argentina/Buenos_Aires', 'Africa/Cairo', 'Africa/Lagos', 'Africa/Johannesburg', 'Africa/Nairobi', 'Asia/Dubai', 'Asia/Karachi', 'Asia/Kolkata', 'Asia/Dhaka', 'Asia/Bangkok', 'Asia/Singapore', 'Asia/Hong_Kong', 'Asia/Shanghai', 'Asia/Tokyo', 'Asia/Seoul', 'Australia/Sydney', 'Pacific/Auckland'];
+
+// Cached result of Intl.supportedValuesOf('timeZone'): undefined = not yet computed,
+// null = the runtime doesn't support it.
+let supportedZones;
+function getSupportedZones() {
+  if (supportedZones === undefined) {
+    supportedZones = typeof Intl.supportedValuesOf === 'function' ? new Set(Intl.supportedValuesOf('timeZone')) : null;
+  }
+  return supportedZones;
+}
+function isValidTimezone(tz) {
+  var _getSupportedZones;
+  // Prefer the runtime's canonical IANA list as a fast path when available.
+  if ((_getSupportedZones = getSupportedZones()) !== null && _getSupportedZones !== void 0 && _getSupportedZones.has(tz)) return true;
+  // Fallback: probe the constructor — it throws a RangeError for unknown timezones. This also
+  // covers valid ids missing from supportedValuesOf, which omits aliases such as 'UTC' and
+  // 'Asia/Calcutta' on some runtimes.
+  try {
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: tz
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * All IANA timezone ids known to the runtime (via `Intl.supportedValuesOf`), or a curated list
+ * of ~30 common zones on runtimes without it.
+ */
+function listTimezones() {
+  const zones = getSupportedZones();
+  return zones ? [...zones] : [...FALLBACK_TIMEZONES];
+}
+
+/**
+ * The current UTC offset of a timezone, e.g. `currentOffset('Asia/Karachi')` → `"UTC+05:00"`.
+ * Computed via `Intl.DateTimeFormat` with `timeZoneName: 'longOffset'`; on older runtimes the
+ * `'short'` style is used instead and may yield an abbreviation (e.g. `"PST"`), which is
+ * returned as-is. Throws a `RangeError` for unknown timezones. Note the offset is "current" —
+ * DST-observing zones return different values across the year.
+ */
+function currentOffset(tz) {
+  var _timeZoneName;
+  const now = new Date();
+  const timeZoneName = style => {
+    try {
+      var _Intl$DateTimeFormat$;
+      return (_Intl$DateTimeFormat$ = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        timeZoneName: style
+      }).formatToParts(now).find(part => part.type === 'timeZoneName')) === null || _Intl$DateTimeFormat$ === void 0 ? void 0 : _Intl$DateTimeFormat$.value;
+    } catch {
+      // Either the runtime doesn't support this timeZoneName style, or tz is unknown.
+      return undefined;
+    }
+  };
+  const raw = (_timeZoneName = timeZoneName('longOffset')) !== null && _timeZoneName !== void 0 ? _timeZoneName : timeZoneName('short');
+  if (raw === undefined) throw new RangeError(`Unknown timezone: "${tz}"`);
+  // Normalise 'GMT+05:00', 'GMT+5:30', 'GMT-7' or bare 'GMT' (UTC) to 'UTC±HH:MM'.
+  const match = /^(?:GMT|UTC)(?:([+-])(\d{1,2})(?::(\d{2}))?)?$/.exec(raw);
+  if (!match) return raw;
+  const [, sign = '+', hours = '0', minutes = '00'] = match;
+  return `UTC${sign}${hours.padStart(2, '0')}:${minutes}`;
+}
+/**
+ * A timezone field storing an IANA timezone id (e.g. `Asia/Karachi`). Built on the core `text`
+ * field; values are validated against `Intl.supportedValuesOf('timeZone')` when available,
+ * otherwise by probing `Intl.DateTimeFormat`. Empty/null values pass through untouched.
+ */
+function timezone(config = {}) {
+  const {
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return fields.text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'IANA timezone, e.g. Asia/Karachi',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !isValidTimezone(value)) {
+          addValidationError('Must be a valid IANA timezone (e.g. "Asia/Karachi")');
+        }
+      }
+    }
+  });
+}
+
+exports.currentOffset = currentOffset;
+exports.listTimezones = listTimezones;
+exports.timezone = timezone;

package/dist/nixxie-cms-fields-timezone.esm.js

@@ -0,0 +1,114 @@
+import { text } from '@nixxie-cms/core/fields';
+
+/** ~30 widely used zones, used only on runtimes without `Intl.supportedValuesOf`. */
+const FALLBACK_TIMEZONES = ['UTC', 'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Europe/Madrid', 'Europe/Rome', 'Europe/Moscow', 'Europe/Istanbul', 'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'America/Toronto', 'America/Mexico_City', 'America/Bogota', 'America/Sao_Paulo', 'America/Argentina/Buenos_Aires', 'Africa/Cairo', 'Africa/Lagos', 'Africa/Johannesburg', 'Africa/Nairobi', 'Asia/Dubai', 'Asia/Karachi', 'Asia/Kolkata', 'Asia/Dhaka', 'Asia/Bangkok', 'Asia/Singapore', 'Asia/Hong_Kong', 'Asia/Shanghai', 'Asia/Tokyo', 'Asia/Seoul', 'Australia/Sydney', 'Pacific/Auckland'];
+
+// Cached result of Intl.supportedValuesOf('timeZone'): undefined = not yet computed,
+// null = the runtime doesn't support it.
+let supportedZones;
+function getSupportedZones() {
+  if (supportedZones === undefined) {
+    supportedZones = typeof Intl.supportedValuesOf === 'function' ? new Set(Intl.supportedValuesOf('timeZone')) : null;
+  }
+  return supportedZones;
+}
+function isValidTimezone(tz) {
+  var _getSupportedZones;
+  // Prefer the runtime's canonical IANA list as a fast path when available.
+  if ((_getSupportedZones = getSupportedZones()) !== null && _getSupportedZones !== void 0 && _getSupportedZones.has(tz)) return true;
+  // Fallback: probe the constructor — it throws a RangeError for unknown timezones. This also
+  // covers valid ids missing from supportedValuesOf, which omits aliases such as 'UTC' and
+  // 'Asia/Calcutta' on some runtimes.
+  try {
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: tz
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * All IANA timezone ids known to the runtime (via `Intl.supportedValuesOf`), or a curated list
+ * of ~30 common zones on runtimes without it.
+ */
+function listTimezones() {
+  const zones = getSupportedZones();
+  return zones ? [...zones] : [...FALLBACK_TIMEZONES];
+}
+
+/**
+ * The current UTC offset of a timezone, e.g. `currentOffset('Asia/Karachi')` → `"UTC+05:00"`.
+ * Computed via `Intl.DateTimeFormat` with `timeZoneName: 'longOffset'`; on older runtimes the
+ * `'short'` style is used instead and may yield an abbreviation (e.g. `"PST"`), which is
+ * returned as-is. Throws a `RangeError` for unknown timezones. Note the offset is "current" —
+ * DST-observing zones return different values across the year.
+ */
+function currentOffset(tz) {
+  var _timeZoneName;
+  const now = new Date();
+  const timeZoneName = style => {
+    try {
+      var _Intl$DateTimeFormat$;
+      return (_Intl$DateTimeFormat$ = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        timeZoneName: style
+      }).formatToParts(now).find(part => part.type === 'timeZoneName')) === null || _Intl$DateTimeFormat$ === void 0 ? void 0 : _Intl$DateTimeFormat$.value;
+    } catch {
+      // Either the runtime doesn't support this timeZoneName style, or tz is unknown.
+      return undefined;
+    }
+  };
+  const raw = (_timeZoneName = timeZoneName('longOffset')) !== null && _timeZoneName !== void 0 ? _timeZoneName : timeZoneName('short');
+  if (raw === undefined) throw new RangeError(`Unknown timezone: "${tz}"`);
+  // Normalise 'GMT+05:00', 'GMT+5:30', 'GMT-7' or bare 'GMT' (UTC) to 'UTC±HH:MM'.
+  const match = /^(?:GMT|UTC)(?:([+-])(\d{1,2})(?::(\d{2}))?)?$/.exec(raw);
+  if (!match) return raw;
+  const [, sign = '+', hours = '0', minutes = '00'] = match;
+  return `UTC${sign}${hours.padStart(2, '0')}:${minutes}`;
+}
+/**
+ * A timezone field storing an IANA timezone id (e.g. `Asia/Karachi`). Built on the core `text`
+ * field; values are validated against `Intl.supportedValuesOf('timeZone')` when available,
+ * otherwise by probing `Intl.DateTimeFormat`. Empty/null values pass through untouched.
+ */
+function timezone(config = {}) {
+  const {
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  const userValidate = hooks === null || hooks === void 0 ? void 0 : hooks.validate;
+  return text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'IANA timezone, e.g. Asia/Karachi',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      validate: async args => {
+        var _userValidate;
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args);else await (userValidate === null || userValidate === void 0 || (_userValidate = userValidate[args.operation]) === null || _userValidate === void 0 ? void 0 : _userValidate.call(userValidate, args));
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0 && !isValidTimezone(value)) {
+          addValidationError('Must be a valid IANA timezone (e.g. "Asia/Karachi")');
+        }
+      }
+    }
+  });
+}
+
+export { currentOffset, listTimezones, timezone };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-timezone",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-timezone.cjs.js",
+  "module": "dist/nixxie-cms-fields-timezone.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-timezone.cjs.js",
+      "module": "./dist/nixxie-cms-fields-timezone.esm.js",
+      "default": "./dist/nixxie-cms-fields-timezone.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/fields-timezone"
+  }
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+import { text } from '@nixxie-cms/core/fields'
+import type { TextFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+/** ~30 widely used zones, used only on runtimes without `Intl.supportedValuesOf`. */
+const FALLBACK_TIMEZONES = [
+  'UTC',
+  'Europe/London',
+  'Europe/Paris',
+  'Europe/Berlin',
+  'Europe/Madrid',
+  'Europe/Rome',
+  'Europe/Moscow',
+  'Europe/Istanbul',
+  'America/New_York',
+  'America/Chicago',
+  'America/Denver',
+  'America/Los_Angeles',
+  'America/Toronto',
+  'America/Mexico_City',
+  'America/Bogota',
+  'America/Sao_Paulo',
+  'America/Argentina/Buenos_Aires',
+  'Africa/Cairo',
+  'Africa/Lagos',
+  'Africa/Johannesburg',
+  'Africa/Nairobi',
+  'Asia/Dubai',
+  'Asia/Karachi',
+  'Asia/Kolkata',
+  'Asia/Dhaka',
+  'Asia/Bangkok',
+  'Asia/Singapore',
+  'Asia/Hong_Kong',
+  'Asia/Shanghai',
+  'Asia/Tokyo',
+  'Asia/Seoul',
+  'Australia/Sydney',
+  'Pacific/Auckland',
+]
+
+// Cached result of Intl.supportedValuesOf('timeZone'): undefined = not yet computed,
+// null = the runtime doesn't support it.
+let supportedZones: ReadonlySet<string> | null | undefined
+
+function getSupportedZones(): ReadonlySet<string> | null {
+  if (supportedZones === undefined) {
+    supportedZones =
+      typeof (Intl as any).supportedValuesOf === 'function'
+        ? new Set<string>((Intl as any).supportedValuesOf('timeZone'))
+        : null
+  }
+  return supportedZones
+}
+
+function isValidTimezone(tz: string): boolean {
+  // Prefer the runtime's canonical IANA list as a fast path when available.
+  if (getSupportedZones()?.has(tz)) return true
+  // Fallback: probe the constructor — it throws a RangeError for unknown timezones. This also
+  // covers valid ids missing from supportedValuesOf, which omits aliases such as 'UTC' and
+  // 'Asia/Calcutta' on some runtimes.
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: tz })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * All IANA timezone ids known to the runtime (via `Intl.supportedValuesOf`), or a curated list
+ * of ~30 common zones on runtimes without it.
+ */
+export function listTimezones(): string[] {
+  const zones = getSupportedZones()
+  return zones ? [...zones] : [...FALLBACK_TIMEZONES]
+}
+
+/**
+ * The current UTC offset of a timezone, e.g. `currentOffset('Asia/Karachi')` → `"UTC+05:00"`.
+ * Computed via `Intl.DateTimeFormat` with `timeZoneName: 'longOffset'`; on older runtimes the
+ * `'short'` style is used instead and may yield an abbreviation (e.g. `"PST"`), which is
+ * returned as-is. Throws a `RangeError` for unknown timezones. Note the offset is "current" —
+ * DST-observing zones return different values across the year.
+ */
+export function currentOffset(tz: string): string {
+  const now = new Date()
+  const timeZoneName = (style: 'longOffset' | 'short'): string | undefined => {
+    try {
+      return new Intl.DateTimeFormat('en-US', { timeZone: tz, timeZoneName: style })
+        .formatToParts(now)
+        .find(part => part.type === 'timeZoneName')?.value
+    } catch {
+      // Either the runtime doesn't support this timeZoneName style, or tz is unknown.
+      return undefined
+    }
+  }
+  const raw = timeZoneName('longOffset') ?? timeZoneName('short')
+  if (raw === undefined) throw new RangeError(`Unknown timezone: "${tz}"`)
+  // Normalise 'GMT+05:00', 'GMT+5:30', 'GMT-7' or bare 'GMT' (UTC) to 'UTC±HH:MM'.
+  const match = /^(?:GMT|UTC)(?:([+-])(\d{1,2})(?::(\d{2}))?)?$/.exec(raw)
+  if (!match) return raw
+  const [, sign = '+', hours = '0', minutes = '00'] = match
+  return `UTC${sign}${hours.padStart(2, '0')}:${minutes}`
+}
+
+export type TimezoneFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  TextFieldConfig<CollectionTypeInfo>,
+  'validation'
+> & {
+  validation?: {
+    /** Reject saving when no value is present. */
+    isRequired?: boolean
+  }
+}
+
+/**
+ * A timezone field storing an IANA timezone id (e.g. `Asia/Karachi`). Built on the core `text`
+ * field; values are validated against `Intl.supportedValuesOf('timeZone')` when available,
+ * otherwise by probing `Intl.DateTimeFormat`. Empty/null values pass through untouched.
+ */
+export function timezone<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: TimezoneFieldConfig<CollectionTypeInfo> = {}
+): FieldTypeFunc<CollectionTypeInfo> {
+  const { hooks, validation, ...rest } = config
+  const userValidate = hooks?.validate as
+    | ((args: any) => unknown)
+    | { create?: (args: any) => unknown; update?: (args: any) => unknown; delete?: (args: any) => unknown }
+    | undefined
+
+  return text<CollectionTypeInfo>({
+    ...(rest as TextFieldConfig<CollectionTypeInfo>),
+    validation: { isRequired: validation?.isRequired },
+    ui: { description: 'IANA timezone, e.g. Asia/Karachi', ...rest.ui },
+    hooks: {
+      ...hooks,
+      validate: async (args: any) => {
+        // Preserve any user-supplied validate hook (function or { create, update, delete } form).
+        if (typeof userValidate === 'function') await userValidate(args)
+        else await userValidate?.[args.operation as 'create' | 'update' | 'delete']?.(args)
+
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (typeof value === 'string' && value.length > 0 && !isValidTimezone(value)) {
+          addValidationError('Must be a valid IANA timezone (e.g. "Asia/Karachi")')
+        }
+      },
+    },
+  })
+}