@melodicdev/components 1.6.2 → 1.6.3

package/README.md

@@ -231,6 +231,12 @@ type ThemeMode = 'light' | 'dark' | 'system';
 
 ---
 
+## Working with timezones
+
+For datetime fields that need to round-trip a real UTC instant — multi-tenant SaaS, calendar/scheduling apps, anything stored as UTC server-side — use [`<ml-date-time-picker>`](./docs/components/forms.md#ml-date-time-picker) with its `timezone` attribute. The picker anchors the wall-clock the user types to the named IANA zone, surfaces a `valueUtc` field on the `ml:change` event detail, and renders a trailing zone label so users know what zone they're entering. Without `timezone`, the component is a plain naive datetime input — no behavior change for existing consumers. Elsewhere in the app, the right primitive for displaying the same instant in another zone is `Intl.DateTimeFormat(..., { timeZone })`.
+
+---
+
 ## Theme System
 
 Override tokens globally via CSS:

package/lib/components/forms/date-time-picker/date-time-picker.component.d.ts

@@ -1,23 +1,61 @@
 import type { IElementRef, OnCreate, OnDestroy } from '@melodicdev/core';
+import type { TimezoneLabelFormat } from './tz-utils.js';
 import '../date-picker/date-picker.component.js';
 import '../time-picker/time-picker.component.js';
 /**
- * ml-date-time-picker - Combined date and time picker
+ * ml-date-time-picker - Combined date and time picker with optional timezone support.
  *
- * Composes ml-date-picker and ml-time-picker into a single control.
- * Value format: ISO datetime string (YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss)
+ * Composes `ml-date-picker` and `ml-time-picker` into a single control.
  *
- * @example
+ * **Without `timezone`** (default): treats `value` as a naive wall-clock
+ * string `YYYY-MM-DDTHH:mm`. Behavior is byte-identical to a plain date+time
+ * input — no UTC conversion happens.
+ *
+ * **With `timezone`** (IANA name, e.g. `America/Detroit`): the picker
+ * anchors the wall-clock the user sees to the named zone. If the incoming
+ * `value` is a UTC ISO string (`...Z` or `±HH:MM` offset), it is parsed as a
+ * real instant and rendered as the equivalent wall-clock in `timezone`. If
+ * the incoming value is naive, it is treated as wall-clock in `timezone`.
+ * The `ml:change` event detail then includes a `valueUtc` field so consumers
+ * can store/round-trip the real UTC instant without zone drift.
+ *
+ * @example Naive (current behavior — unchanged)
  * ```html
  * <ml-date-time-picker label="Event start" value="2026-02-08T09:30"></ml-date-time-picker>
- * <ml-date-time-picker label="Meeting" use-12-hour></ml-date-time-picker>
  * ```
  *
- * @fires ml:change - Emitted when value changes. Detail: { value: string, date: string, time: string }
+ * @example Timezone-anchored
+ * ```html
+ * <ml-date-time-picker
+ *   label="Event start"
+ *   timezone="America/Detroit"
+ *   value="2026-04-27T13:00:00Z"
+ *   timezone-label="short"
+ *   viewer-hint
+ * ></ml-date-time-picker>
+ * ```
+ *
+ * Then in the consumer:
+ * ```ts
+ * picker.addEventListener('ml:change', (e) => {
+ *   // e.detail.value    → naive wall-clock in the picker's zone
+ *   // e.detail.valueUtc → '2026-04-27T13:00:00.000Z' — POST this to your API
+ *   // e.detail.timezone → 'America/Detroit'
+ *   fetch('/api/events', { method: 'POST', body: JSON.stringify({ startsAt: e.detail.valueUtc }) });
+ * });
+ * ```
+ *
+ * @fires ml:change - Detail: `{ value: string, date: string, time: string, valueUtc?: string, timezone?: string }`
  */
 export declare class DateTimePickerComponent implements IElementRef, OnCreate, OnDestroy {
     elementRef: HTMLElement;
-    /** Selected datetime in ISO format (YYYY-MM-DDTHH:mm) */
+    /**
+     * Selected datetime.
+     *
+     * - When `timezone` is unset: a naive `YYYY-MM-DDTHH:mm` string.
+     * - When `timezone` is set: either a UTC ISO string (`...Z`/`±HH:MM`)
+     *   or a naive `YYYY-MM-DDTHH:mm` interpreted as wall-clock in `timezone`.
+     */
     value: string;
     /** Placeholder text */
     placeholder: string;
@@ -45,15 +83,49 @@ export declare class DateTimePickerComponent implements IElementRef, OnCreate, O
     step: number;
     /** Use 12-hour format (default: true) */
     twelveHour: boolean;
-    /** Internal date portion */
+    /**
+     * IANA timezone name (e.g. `America/Detroit`). When set, the picker
+     * interprets/emits values anchored to this zone. When unset (default),
+     * values are naive wall-clock strings.
+     */
+    timezone: string;
+    /**
+     * How to render the trailing timezone label.
+     *
+     * - `short`  → `EDT`
+     * - `long`   → `Eastern Daylight Time`
+     * - `offset` → `GMT-4`
+     * - `none`   → don't render a label
+     */
+    timezoneLabel: TimezoneLabelFormat;
+    /**
+     * When true AND the browser's UTC offset differs from `timezone` at the
+     * current value's instant, render a small subdued line below the input
+     * showing the equivalent wall-clock in the viewer's local zone.
+     */
+    viewerHint: boolean;
+    /** Internal date portion (always naive YYYY-MM-DD in the picker's zone) */
     dateValue: string;
-    /** Internal time portion */
+    /** Internal time portion (always naive HH:mm in the picker's zone) */
     timeValue: string;
     private _listeners;
+    private _lastSyncedValue;
     get use12Hour(): boolean;
     get displayValue(): string;
+    /** The naive wall-clock string the user sees, regardless of input format. */
+    get naiveValue(): string;
+    /** Derived UTC ISO for the current naive value. Empty string when no timezone. */
+    get valueUtc(): string;
+    /** Trailing timezone label text (e.g. `EDT`). Empty when no timezone or label='none'. */
+    get tzLabelText(): string;
+    /** Whether the viewer-hint line should be shown right now. */
+    get showViewerHint(): boolean;
+    /** Pre-rendered viewer hint text (e.g. `(6:00 AM PDT your time)`). */
+    get viewerHintText(): string;
     onCreate(): void;
     onDestroy(): void;
+    onPropertyChange(name: string, _oldVal: unknown, _newVal: unknown): void;
+    private currentInstant;
     private syncFromValue;
     private attachChildListeners;
     private emitChange;

package/lib/components/forms/date-time-picker/date-time-picker.component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-time-picker.component.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.component.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAczE,OAAO,yCAAyC,CAAC;AACjD,OAAO,yCAAyC,CAAC;AAiCjD;;;;;;;;;;;;;GAaG;AACH,qBAMa,uBAAwB,YAAW,WAAW,EAAE,QAAQ,EAAE,SAAS;IACxE,UAAU,EAAG,WAAW,CAAC;IAEhC,yDAAyD;IAClD,KAAK,SAAM;IAElB,uBAAuB;IAChB,WAAW,SAA0B;IAE5C,kBAAkB;IACX,KAAK,SAAM;IAElB,gBAAgB;IACT,IAAI,SAAM;IAEjB,oBAAoB;IACb,KAAK,SAAM;IAElB,iBAAiB;IACV,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEvC,qBAAqB;IACd,QAAQ,UAAS;IAExB,qBAAqB;IACd,QAAQ,UAAS;IAExB,2CAA2C;IACpC,OAAO,SAAM;IAEpB,2CAA2C;IACpC,OAAO,SAAM;IAEpB,sCAAsC;IAC/B,OAAO,SAAM;IAEpB,sCAAsC;IAC/B,OAAO,SAAM;IAEpB,2BAA2B;IACpB,IAAI,SAAM;IAEjB,yCAAyC;IAClC,UAAU,UAAQ;IAEzB,4BAA4B;IACrB,SAAS,SAAM;IAEtB,4BAA4B;IACrB,SAAS,SAAM;IAEtB,OAAO,CAAC,UAAU,CAAyB;IAE3C,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,IAAW,YAAY,IAAI,MAAM,CAEhC;IAEM,QAAQ,IAAI,IAAI;IAKhB,SAAS,IAAI,IAAI;IAKxB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,oBAAoB;IA+E5B,OAAO,CAAC,UAAU;CAqBlB"}
+{"version":3,"file":"date-time-picker.component.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.component.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAYzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAWzD,OAAO,yCAAyC,CAAC;AACjD,OAAO,yCAAyC,CAAC;AAiCjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAMa,uBAAwB,YAAW,WAAW,EAAE,QAAQ,EAAE,SAAS;IACxE,UAAU,EAAG,WAAW,CAAC;IAEhC;;;;;;OAMG;IACI,KAAK,SAAM;IAElB,uBAAuB;IAChB,WAAW,SAA0B;IAE5C,kBAAkB;IACX,KAAK,SAAM;IAElB,gBAAgB;IACT,IAAI,SAAM;IAEjB,oBAAoB;IACb,KAAK,SAAM;IAElB,iBAAiB;IACV,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEvC,qBAAqB;IACd,QAAQ,UAAS;IAExB,qBAAqB;IACd,QAAQ,UAAS;IAExB,2CAA2C;IACpC,OAAO,SAAM;IAEpB,2CAA2C;IACpC,OAAO,SAAM;IAEpB,sCAAsC;IAC/B,OAAO,SAAM;IAEpB,sCAAsC;IAC/B,OAAO,SAAM;IAEpB,2BAA2B;IACpB,IAAI,SAAM;IAEjB,yCAAyC;IAClC,UAAU,UAAQ;IAEzB;;;;OAIG;IACI,QAAQ,SAAM;IAErB;;;;;;;OAOG;IACI,aAAa,EAAE,mBAAmB,CAAW;IAEpD;;;;OAIG;IACI,UAAU,UAAS;IAE1B,2EAA2E;IACpE,SAAS,SAAM;IAEtB,sEAAsE;IAC/D,SAAS,SAAM;IAEtB,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,gBAAgB,CAAM;IAE9B,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED,6EAA6E;IAC7E,IAAW,UAAU,IAAI,MAAM,CAK9B;IAED,kFAAkF;IAClF,IAAW,QAAQ,IAAI,MAAM,CAK5B;IAED,yFAAyF;IACzF,IAAW,WAAW,IAAI,MAAM,CAI/B;IAED,8DAA8D;IAC9D,IAAW,cAAc,IAAI,OAAO,CAKnC;IAED,sEAAsE;IACtE,IAAW,cAAc,IAAI,MAAM,CAKlC;IAEM,QAAQ,IAAI,IAAI;IAKhB,SAAS,IAAI,IAAI;IAKjB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAQ/E,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,oBAAoB;IA+E5B,OAAO,CAAC,UAAU;CA8BlB"}

package/lib/components/forms/date-time-picker/date-time-picker.component.js

@@ -8,6 +8,7 @@ import { MelodicComponent } from '@melodicdev/core';
 import { registerAdapter } from '@melodicdev/core/forms';
 import { dateTimePickerTemplate } from './date-time-picker.template.js';
 import { dateTimePickerStyles } from './date-time-picker.styles.js';
+import { formatTimezoneLabel, formatViewerHint, isUtcIsoString, naiveToUtcIso, utcToNaive, viewerOffsetDiffersAt } from './tz-utils.js';
 registerAdapter((el) => el.tagName === 'ML-DATE-TIME-PICKER', {
     inputEvent: 'ml:change',
     blurEvent: 'focusout',
@@ -51,22 +52,59 @@ function formatDateTimeDisplay(value, use12Hour) {
     return display;
 }
 /**
- * ml-date-time-picker - Combined date and time picker
+ * ml-date-time-picker - Combined date and time picker with optional timezone support.
  *
- * Composes ml-date-picker and ml-time-picker into a single control.
- * Value format: ISO datetime string (YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss)
+ * Composes `ml-date-picker` and `ml-time-picker` into a single control.
  *
- * @example
+ * **Without `timezone`** (default): treats `value` as a naive wall-clock
+ * string `YYYY-MM-DDTHH:mm`. Behavior is byte-identical to a plain date+time
+ * input — no UTC conversion happens.
+ *
+ * **With `timezone`** (IANA name, e.g. `America/Detroit`): the picker
+ * anchors the wall-clock the user sees to the named zone. If the incoming
+ * `value` is a UTC ISO string (`...Z` or `±HH:MM` offset), it is parsed as a
+ * real instant and rendered as the equivalent wall-clock in `timezone`. If
+ * the incoming value is naive, it is treated as wall-clock in `timezone`.
+ * The `ml:change` event detail then includes a `valueUtc` field so consumers
+ * can store/round-trip the real UTC instant without zone drift.
+ *
+ * @example Naive (current behavior — unchanged)
  * ```html
  * <ml-date-time-picker label="Event start" value="2026-02-08T09:30"></ml-date-time-picker>
- * <ml-date-time-picker label="Meeting" use-12-hour></ml-date-time-picker>
  * ```
  *
- * @fires ml:change - Emitted when value changes. Detail: { value: string, date: string, time: string }
+ * @example Timezone-anchored
+ * ```html
+ * <ml-date-time-picker
+ *   label="Event start"
+ *   timezone="America/Detroit"
+ *   value="2026-04-27T13:00:00Z"
+ *   timezone-label="short"
+ *   viewer-hint
+ * ></ml-date-time-picker>
+ * ```
+ *
+ * Then in the consumer:
+ * ```ts
+ * picker.addEventListener('ml:change', (e) => {
+ *   // e.detail.value    → naive wall-clock in the picker's zone
+ *   // e.detail.valueUtc → '2026-04-27T13:00:00.000Z' — POST this to your API
+ *   // e.detail.timezone → 'America/Detroit'
+ *   fetch('/api/events', { method: 'POST', body: JSON.stringify({ startsAt: e.detail.valueUtc }) });
+ * });
+ * ```
+ *
+ * @fires ml:change - Detail: `{ value: string, date: string, time: string, valueUtc?: string, timezone?: string }`
  */
 let DateTimePickerComponent = class DateTimePickerComponent {
     constructor() {
-        /** Selected datetime in ISO format (YYYY-MM-DDTHH:mm) */
+        /**
+         * Selected datetime.
+         *
+         * - When `timezone` is unset: a naive `YYYY-MM-DDTHH:mm` string.
+         * - When `timezone` is set: either a UTC ISO string (`...Z`/`±HH:MM`)
+         *   or a naive `YYYY-MM-DDTHH:mm` interpreted as wall-clock in `timezone`.
+         */
         this.value = '';
         /** Placeholder text */
         this.placeholder = 'Select date and time';
@@ -94,17 +132,82 @@ let DateTimePickerComponent = class DateTimePickerComponent {
         this.step = 15;
         /** Use 12-hour format (default: true) */
         this.twelveHour = true;
-        /** Internal date portion */
+        /**
+         * IANA timezone name (e.g. `America/Detroit`). When set, the picker
+         * interprets/emits values anchored to this zone. When unset (default),
+         * values are naive wall-clock strings.
+         */
+        this.timezone = '';
+        /**
+         * How to render the trailing timezone label.
+         *
+         * - `short`  → `EDT`
+         * - `long`   → `Eastern Daylight Time`
+         * - `offset` → `GMT-4`
+         * - `none`   → don't render a label
+         */
+        this.timezoneLabel = 'short';
+        /**
+         * When true AND the browser's UTC offset differs from `timezone` at the
+         * current value's instant, render a small subdued line below the input
+         * showing the equivalent wall-clock in the viewer's local zone.
+         */
+        this.viewerHint = false;
+        /** Internal date portion (always naive YYYY-MM-DD in the picker's zone) */
         this.dateValue = '';
-        /** Internal time portion */
+        /** Internal time portion (always naive HH:mm in the picker's zone) */
         this.timeValue = '';
         this._listeners = [];
+        this._lastSyncedValue = '';
     }
     get use12Hour() {
         return this.twelveHour;
     }
     get displayValue() {
-        return formatDateTimeDisplay(this.value, this.use12Hour);
+        return formatDateTimeDisplay(this.naiveValue, this.use12Hour);
+    }
+    /** The naive wall-clock string the user sees, regardless of input format. */
+    get naiveValue() {
+        if (this.dateValue && this.timeValue)
+            return `${this.dateValue}T${this.timeValue}`;
+        if (this.dateValue)
+            return this.dateValue;
+        if (this.timeValue)
+            return this.timeValue;
+        return '';
+    }
+    /** Derived UTC ISO for the current naive value. Empty string when no timezone. */
+    get valueUtc() {
+        if (!this.timezone)
+            return '';
+        const naive = this.naiveValue;
+        if (!naive || !naive.includes('T'))
+            return '';
+        return naiveToUtcIso(naive, this.timezone);
+    }
+    /** Trailing timezone label text (e.g. `EDT`). Empty when no timezone or label='none'. */
+    get tzLabelText() {
+        if (!this.timezone || this.timezoneLabel === 'none')
+            return '';
+        const instant = this.currentInstant() ?? new Date();
+        return formatTimezoneLabel(instant, this.timezone, this.timezoneLabel);
+    }
+    /** Whether the viewer-hint line should be shown right now. */
+    get showViewerHint() {
+        if (!this.viewerHint || !this.timezone)
+            return false;
+        const instant = this.currentInstant();
+        if (!instant)
+            return false;
+        return viewerOffsetDiffersAt(instant, this.timezone);
+    }
+    /** Pre-rendered viewer hint text (e.g. `(6:00 AM PDT your time)`). */
+    get viewerHintText() {
+        const instant = this.currentInstant();
+        if (!instant)
+            return '';
+        const { wallClock, label } = formatViewerHint(instant, 'short');
+        return label ? `(${wallClock} ${label} your time)` : `(${wallClock} your time)`;
     }
     onCreate() {
         this.syncFromValue();
@@ -115,10 +218,44 @@ let DateTimePickerComponent = class DateTimePickerComponent {
             cleanup();
         this._listeners = [];
     }
+    onPropertyChange(name, _oldVal, _newVal) {
+        if (name === 'value' || name === 'timezone') {
+            // Re-derive internal date/time when the inbound value (or its
+            // anchor zone) changes from outside the component.
+            queueMicrotask(() => this.syncFromValue());
+        }
+    }
+    currentInstant() {
+        if (!this.timezone)
+            return null;
+        const utcIso = this.valueUtc;
+        if (!utcIso)
+            return null;
+        const d = new Date(utcIso);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
     syncFromValue() {
-        if (!this.value)
+        const incoming = this.value ?? '';
+        if (incoming === this._lastSyncedValue)
+            return;
+        this._lastSyncedValue = incoming;
+        if (!incoming) {
+            this.dateValue = '';
+            this.timeValue = '';
             return;
-        const [datePart, timePart] = this.value.split('T');
+        }
+        // With a timezone AND a UTC ISO input, project onto the zone's wall-clock.
+        if (this.timezone && isUtcIsoString(incoming)) {
+            const naive = utcToNaive(incoming, this.timezone);
+            const [datePart, timePart] = naive.split('T');
+            if (datePart)
+                this.dateValue = datePart;
+            if (timePart)
+                this.timeValue = timePart;
+            return;
+        }
+        // Otherwise treat incoming as naive (zoned or unzoned — both render the same).
+        const [datePart, timePart] = incoming.split('T');
         if (datePart)
             this.dateValue = datePart;
         if (timePart)
@@ -197,23 +334,23 @@ let DateTimePickerComponent = class DateTimePickerComponent {
         }
     }
     emitChange() {
-        if (this.dateValue && this.timeValue) {
-            this.value = `${this.dateValue}T${this.timeValue}`;
-        }
-        else if (this.dateValue) {
-            this.value = this.dateValue;
-        }
-        else if (this.timeValue) {
-            this.value = this.timeValue;
+        this.value = this.naiveValue;
+        this._lastSyncedValue = this.value;
+        const detail = {
+            value: this.value,
+            date: this.dateValue,
+            time: this.timeValue
+        };
+        if (this.timezone) {
+            detail.timezone = this.timezone;
+            const utc = this.valueUtc;
+            if (utc)
+                detail.valueUtc = utc;
         }
         this.elementRef.dispatchEvent(new CustomEvent('ml:change', {
             bubbles: true,
             composed: true,
-            detail: {
-                value: this.value,
-                date: this.dateValue,
-                time: this.timeValue
-            }
+            detail
         }));
     }
 };
@@ -222,7 +359,7 @@ DateTimePickerComponent = __decorate([
         selector: 'ml-date-time-picker',
         template: dateTimePickerTemplate,
         styles: dateTimePickerStyles,
-        attributes: ['value', 'placeholder', 'label', 'hint', 'error', 'size', 'disabled', 'required', 'min-date', 'max-date', 'min-time', 'max-time', 'step', 'twelve-hour']
+        attributes: ['value', 'placeholder', 'label', 'hint', 'error', 'size', 'disabled', 'required', 'min-date', 'max-date', 'min-time', 'max-time', 'step', 'twelve-hour', 'timezone', 'timezone-label', 'viewer-hint']
     })
 ], DateTimePickerComponent);
 export { DateTimePickerComponent };

package/lib/components/forms/date-time-picker/date-time-picker.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-time-picker.styles.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,iDAgIhC,CAAC"}
+{"version":3,"file":"date-time-picker.styles.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,iDAgKhC,CAAC"}

package/lib/components/forms/date-time-picker/date-time-picker.styles.js

@@ -39,6 +39,17 @@ export const dateTimePickerStyles = () => css `
 		--ml-date-time-picker-hint-color: var(--ml-color-text-muted);
 		--ml-date-time-picker-hint-font-size: var(--ml-text-sm);
 
+		/* --- Timezone label --- */
+		--ml-date-time-picker-tz-label-color: var(--ml-color-text-muted);
+		--ml-date-time-picker-tz-label-font-size: var(--ml-text-sm);
+		--ml-date-time-picker-tz-label-font-weight: var(--ml-font-medium);
+		--ml-date-time-picker-tz-label-padding-x: var(--ml-space-2-5);
+
+		/* --- Viewer hint (subdued line below input) --- */
+		--ml-date-time-picker-viewer-hint-color: var(--ml-color-text-muted);
+		--ml-date-time-picker-viewer-hint-font-size: var(--ml-text-xs);
+		--ml-date-time-picker-viewer-hint-margin-top: var(--ml-space-1);
+
 		/* --- Transition --- */
 		--ml-date-time-picker-transition-duration: var(--ml-duration-150);
 		--ml-date-time-picker-transition-easing: var(--ml-ease-in-out);
@@ -104,6 +115,27 @@ export const dateTimePickerStyles = () => css `
 		flex-shrink: 0;
 	}
 
+	/* Timezone label (e.g. EDT) trailing the inputs */
+	.ml-date-time-picker__tz-label {
+		display: inline-flex;
+		align-items: center;
+		padding: 0 var(--ml-date-time-picker-tz-label-padding-x);
+		font-size: var(--ml-date-time-picker-tz-label-font-size);
+		font-weight: var(--ml-date-time-picker-tz-label-font-weight);
+		color: var(--ml-date-time-picker-tz-label-color);
+		flex-shrink: 0;
+		user-select: none;
+	}
+
+	/* Viewer-hint line: shows the same instant in the viewer's local zone */
+	.ml-date-time-picker__viewer-hint {
+		display: block;
+		margin-top: var(--ml-date-time-picker-viewer-hint-margin-top);
+		font-size: var(--ml-date-time-picker-viewer-hint-font-size);
+		color: var(--ml-date-time-picker-viewer-hint-color);
+		line-height: var(--ml-date-time-picker-label-line-height);
+	}
+
 	/* Disabled */
 	.ml-date-time-picker--disabled .ml-date-time-picker__row {
 		opacity: var(--ml-date-time-picker-disabled-opacity);

package/lib/components/forms/date-time-picker/date-time-picker.template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-time-picker.template.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.template.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,uBAAuB,6CA+ChE"}
+{"version":3,"file":"date-time-picker.template.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/date-time-picker.template.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE/E,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,uBAAuB,6CAuDhE"}

package/lib/components/forms/date-time-picker/date-time-picker.template.js

@@ -37,8 +37,16 @@ export function dateTimePickerTemplate(c) {
 					.twelveHour=${c.use12Hour}
 					placeholder="Select time"
 				></ml-time-picker>
+
+				${when(!!c.tzLabelText, () => html `
+					<span class="ml-date-time-picker__tz-label" aria-label="Timezone">${c.tzLabelText}</span>
+				`)}
 			</div>
 
+			${when(c.showViewerHint, () => html `
+				<span class="ml-date-time-picker__viewer-hint">${c.viewerHintText}</span>
+			`)}
+
 			${when(!!c.error, () => html `<span class="ml-date-time-picker__error">${c.error}</span>`, () => html `${when(!!c.hint, () => html `<span class="ml-date-time-picker__hint">${c.hint}</span>`)}`)}
 		</div>
 	`;

package/lib/components/forms/date-time-picker/tz-utils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Timezone helpers for ml-date-time-picker.
+ *
+ * These functions translate between a naive wall-clock string
+ * (`YYYY-MM-DDTHH:mm[:ss]`) and a real UTC instant, anchored to an IANA
+ * timezone name (e.g. `America/Detroit`). All conversions are done via
+ * `Intl.DateTimeFormat` offset reflection — there are no hardcoded zone
+ * tables.
+ *
+ * DST policy:
+ *  - Spring-forward gap (e.g. 2026-03-08 02:30 in America/Detroit doesn't
+ *    exist) resolves to the post-jump wall clock, i.e. the input is
+ *    interpreted one hour forward (03:30 EDT in this example).
+ *  - Fall-back ambiguity (e.g. 2026-11-01 01:30 happens twice) resolves
+ *    to the FIRST occurrence (still-DST / EDT). This matches RFC 5545
+ *    VTIMEZONE behavior and the default in major calendar apps.
+ */
+export type TimezoneLabelFormat = 'short' | 'long' | 'offset' | 'none';
+export declare function isUtcIsoString(value: string): boolean;
+export declare function isNaiveDateTime(value: string): boolean;
+/** Offset of `timeZone` relative to UTC at `date`, in milliseconds (positive = ahead of UTC). */
+export declare function getZoneOffsetMs(date: Date, timeZone: string): number;
+/**
+ * Convert a naive wall-clock string to a real UTC instant, treating the
+ * naive value as a wall clock in `timeZone`.
+ *
+ * Returns the UTC ISO 8601 string with `Z` suffix.
+ */
+export declare function naiveToUtcIso(naive: string, timeZone: string): string;
+/**
+ * Convert a UTC instant (Date or ISO string) to a naive wall-clock string
+ * in `timeZone`. Output format: `YYYY-MM-DDTHH:mm`.
+ */
+export declare function utcToNaive(instant: Date | string, timeZone: string): string;
+/**
+ * Format a timezone name/abbreviation/offset for display next to the input.
+ *
+ * - `short`  → `EDT`
+ * - `long`   → `Eastern Daylight Time`
+ * - `offset` → `GMT-4`
+ * - `none`   → `''`
+ */
+export declare function formatTimezoneLabel(instant: Date, timeZone: string, format: TimezoneLabelFormat): string;
+/** Resolves the browser's local IANA timezone, falling back to UTC. */
+export declare function getLocalTimeZone(): string;
+/**
+ * True iff `timeZone` produces a different UTC offset from the viewer's
+ * local zone at the given instant. Compares offsets, not zone names —
+ * `America/Detroit` and `America/New_York` won't trigger this because
+ * they share an offset year-round.
+ */
+export declare function viewerOffsetDiffersAt(instant: Date, timeZone: string): boolean;
+/**
+ * Render the viewer's local wall-clock + tz label for the given UTC instant.
+ * Used by the optional `viewer-hint` line.
+ */
+export declare function formatViewerHint(instant: Date, format?: TimezoneLabelFormat): {
+    wallClock: string;
+    label: string;
+};
+//# sourceMappingURL=tz-utils.d.ts.map

package/lib/components/forms/date-time-picker/tz-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tz-utils.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/date-time-picker/tz-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAKvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAoCD,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQrE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,IAAI,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GACzB,MAAM,CAWR;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,GAAE,mBAA6B,GAAG;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd,CAYA"}

package/lib/components/forms/date-time-picker/tz-utils.js

@@ -0,0 +1,145 @@
+/**
+ * Timezone helpers for ml-date-time-picker.
+ *
+ * These functions translate between a naive wall-clock string
+ * (`YYYY-MM-DDTHH:mm[:ss]`) and a real UTC instant, anchored to an IANA
+ * timezone name (e.g. `America/Detroit`). All conversions are done via
+ * `Intl.DateTimeFormat` offset reflection — there are no hardcoded zone
+ * tables.
+ *
+ * DST policy:
+ *  - Spring-forward gap (e.g. 2026-03-08 02:30 in America/Detroit doesn't
+ *    exist) resolves to the post-jump wall clock, i.e. the input is
+ *    interpreted one hour forward (03:30 EDT in this example).
+ *  - Fall-back ambiguity (e.g. 2026-11-01 01:30 happens twice) resolves
+ *    to the FIRST occurrence (still-DST / EDT). This matches RFC 5545
+ *    VTIMEZONE behavior and the default in major calendar apps.
+ */
+const NAIVE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?$/;
+const UTC_RE = /(?:Z|[+-]\d{2}:?\d{2})$/;
+export function isUtcIsoString(value) {
+    return !!value && UTC_RE.test(value);
+}
+export function isNaiveDateTime(value) {
+    return !!value && NAIVE_RE.test(value);
+}
+function getZonedParts(date, timeZone) {
+    const fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit'
+    });
+    const parts = {};
+    for (const p of fmt.formatToParts(date)) {
+        if (p.type !== 'literal')
+            parts[p.type] = p.value;
+    }
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour) === 24 ? 0 : Number(parts.hour),
+        minute: Number(parts.minute),
+        second: Number(parts.second)
+    };
+}
+/** Offset of `timeZone` relative to UTC at `date`, in milliseconds (positive = ahead of UTC). */
+export function getZoneOffsetMs(date, timeZone) {
+    const p = getZonedParts(date, timeZone);
+    const asUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+    return asUtc - date.getTime();
+}
+/**
+ * Convert a naive wall-clock string to a real UTC instant, treating the
+ * naive value as a wall clock in `timeZone`.
+ *
+ * Returns the UTC ISO 8601 string with `Z` suffix.
+ */
+export function naiveToUtcIso(naive, timeZone) {
+    if (!naive)
+        return '';
+    const padded = naive.length === 16 ? `${naive}:00` : naive;
+    const naiveAsUtc = new Date(`${padded}Z`);
+    if (Number.isNaN(naiveAsUtc.getTime()))
+        return '';
+    const offset = getZoneOffsetMs(naiveAsUtc, timeZone);
+    const real = new Date(naiveAsUtc.getTime() - offset);
+    return real.toISOString();
+}
+/**
+ * Convert a UTC instant (Date or ISO string) to a naive wall-clock string
+ * in `timeZone`. Output format: `YYYY-MM-DDTHH:mm`.
+ */
+export function utcToNaive(instant, timeZone) {
+    const date = typeof instant === 'string' ? new Date(instant) : instant;
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const p = getZonedParts(date, timeZone);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${p.year}-${pad(p.month)}-${pad(p.day)}T${pad(p.hour)}:${pad(p.minute)}`;
+}
+/**
+ * Format a timezone name/abbreviation/offset for display next to the input.
+ *
+ * - `short`  → `EDT`
+ * - `long`   → `Eastern Daylight Time`
+ * - `offset` → `GMT-4`
+ * - `none`   → `''`
+ */
+export function formatTimezoneLabel(instant, timeZone, format) {
+    if (format === 'none' || !timeZone)
+        return '';
+    const timeZoneName = format === 'long' ? 'long' : format === 'offset' ? 'shortOffset' : 'short';
+    try {
+        const fmt = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName });
+        const part = fmt.formatToParts(instant).find((p) => p.type === 'timeZoneName');
+        return part?.value ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Resolves the browser's local IANA timezone, falling back to UTC. */
+export function getLocalTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+/**
+ * True iff `timeZone` produces a different UTC offset from the viewer's
+ * local zone at the given instant. Compares offsets, not zone names —
+ * `America/Detroit` and `America/New_York` won't trigger this because
+ * they share an offset year-round.
+ */
+export function viewerOffsetDiffersAt(instant, timeZone) {
+    const local = getLocalTimeZone();
+    if (!timeZone || local === timeZone)
+        return false;
+    return getZoneOffsetMs(instant, local) !== getZoneOffsetMs(instant, timeZone);
+}
+/**
+ * Render the viewer's local wall-clock + tz label for the given UTC instant.
+ * Used by the optional `viewer-hint` line.
+ */
+export function formatViewerHint(instant, format = 'short') {
+    const local = getLocalTimeZone();
+    const naive = utcToNaive(instant, local);
+    const [, time] = naive.split('T');
+    const [hStr, mStr] = (time ?? '').split(':');
+    const h24 = Number(hStr);
+    const period = h24 >= 12 ? 'PM' : 'AM';
+    let h12 = h24 % 12;
+    if (h12 === 0)
+        h12 = 12;
+    const wallClock = `${h12}:${mStr} ${period}`;
+    const label = formatTimezoneLabel(instant, local, format);
+    return { wallClock, label };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@melodicdev/components",
-	"version": "1.6.2",
+	"version": "1.6.3",
 	"description": "Themeable UI component library built on the Melodic Framework",
 	"license": "MIT",
 	"author": "Melodic Development",