@melodicdev/components 1.6.1 → 1.6.3

package/assets/melodic-components.min.js

@@ -12140,6 +12140,7 @@ function Uo(e) {
 							`)}
 							${k(e.columns, (t) => t.key, (t) => i`
 								<th
+									part="header-cell"
 									class=${g({
     "ml-table__th": !0,
     "ml-table__th--sortable": !!t.sortable,
@@ -12172,6 +12173,7 @@ function Uo(e) {
     const a = e.startIndex + r;
     return i`
 								<tr
+									part="row"
 									class=${g({
       "ml-table__row": !0,
       "ml-table__row--selected": e.isRowSelected(a)
@@ -12191,10 +12193,13 @@ function Uo(e) {
 										</td>
 									`)}
 									${k(e.columns, (l) => l.key, (l) => i`
-										<td class=${g({
+										<td
+											part="cell"
+											class=${g({
       "ml-table__td": !0,
       [`ml-table__td--${l.align ?? "left"}`]: !0
-    })}>
+    })}
+										>
 											${Ko(l, t, a)}
 										</td>
 									`)}
@@ -12267,6 +12272,16 @@ const Wo = () => _`
 
 		/* ── Table: cells ── */
 		--ml-table-cell-color: var(--ml-color-text);
+		--ml-table-cell-padding-y: var(--ml-space-4);
+		--ml-table-cell-padding-x: var(--ml-space-6);
+		--ml-table-cell-padding-y-sm: var(--ml-space-2-5);
+		--ml-table-cell-padding-x-sm: var(--ml-space-4);
+
+		/* ── Table: header cells ── */
+		--ml-table-header-padding-y: var(--ml-space-3);
+		--ml-table-header-padding-x: var(--ml-space-6);
+		--ml-table-header-padding-y-sm: var(--ml-space-2);
+		--ml-table-header-padding-x-sm: var(--ml-space-4);
 
 		/* ── Table: checkbox ── */
 		--ml-table-checkbox-accent: var(--ml-color-primary);
@@ -12338,7 +12353,7 @@ const Wo = () => _`
 	}
 
 	.ml-table__th {
-		padding: var(--ml-space-3) var(--ml-space-6);
+		padding: var(--ml-table-header-padding-y) var(--ml-table-header-padding-x);
 		font-size: var(--ml-text-xs);
 		font-weight: var(--ml-font-medium);
 		color: var(--ml-table-header-color);
@@ -12350,7 +12365,7 @@ const Wo = () => _`
 	}
 
 	.ml-table--sm .ml-table__th {
-		padding: var(--ml-space-2) var(--ml-space-4);
+		padding: var(--ml-table-header-padding-y-sm) var(--ml-table-header-padding-x-sm);
 	}
 
 	.ml-table__th--center { text-align: center; }
@@ -12428,14 +12443,14 @@ const Wo = () => _`
 
 	/* ── Body cells ── */
 	.ml-table__td {
-		padding: var(--ml-space-4) var(--ml-space-6);
+		padding: var(--ml-table-cell-padding-y) var(--ml-table-cell-padding-x);
 		font-size: var(--ml-text-sm);
 		color: var(--ml-table-cell-color);
 		vertical-align: middle;
 	}
 
 	.ml-table--sm .ml-table__td {
-		padding: var(--ml-space-2-5) var(--ml-space-4);
+		padding: var(--ml-table-cell-padding-y-sm) var(--ml-table-cell-padding-x-sm);
 		font-size: var(--ml-text-xs);
 	}
 

package/lib/components/data-display/table/table.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.styles.d.ts","sourceRoot":"","sources":["../../../../src/components/data-display/table/table.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,iDAuSvB,CAAC"}
+{"version":3,"file":"table.styles.d.ts","sourceRoot":"","sources":["../../../../src/components/data-display/table/table.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,iDAiTvB,CAAC"}

package/lib/components/data-display/table/table.styles.js

@@ -47,6 +47,16 @@ export const tableStyles = () => css `
 
 		/* ── Table: cells ── */
 		--ml-table-cell-color: var(--ml-color-text);
+		--ml-table-cell-padding-y: var(--ml-space-4);
+		--ml-table-cell-padding-x: var(--ml-space-6);
+		--ml-table-cell-padding-y-sm: var(--ml-space-2-5);
+		--ml-table-cell-padding-x-sm: var(--ml-space-4);
+
+		/* ── Table: header cells ── */
+		--ml-table-header-padding-y: var(--ml-space-3);
+		--ml-table-header-padding-x: var(--ml-space-6);
+		--ml-table-header-padding-y-sm: var(--ml-space-2);
+		--ml-table-header-padding-x-sm: var(--ml-space-4);
 
 		/* ── Table: checkbox ── */
 		--ml-table-checkbox-accent: var(--ml-color-primary);
@@ -118,7 +128,7 @@ export const tableStyles = () => css `
 	}
 
 	.ml-table__th {
-		padding: var(--ml-space-3) var(--ml-space-6);
+		padding: var(--ml-table-header-padding-y) var(--ml-table-header-padding-x);
 		font-size: var(--ml-text-xs);
 		font-weight: var(--ml-font-medium);
 		color: var(--ml-table-header-color);
@@ -130,7 +140,7 @@ export const tableStyles = () => css `
 	}
 
 	.ml-table--sm .ml-table__th {
-		padding: var(--ml-space-2) var(--ml-space-4);
+		padding: var(--ml-table-header-padding-y-sm) var(--ml-table-header-padding-x-sm);
 	}
 
 	.ml-table__th--center { text-align: center; }
@@ -208,14 +218,14 @@ export const tableStyles = () => css `
 
 	/* ── Body cells ── */
 	.ml-table__td {
-		padding: var(--ml-space-4) var(--ml-space-6);
+		padding: var(--ml-table-cell-padding-y) var(--ml-table-cell-padding-x);
 		font-size: var(--ml-text-sm);
 		color: var(--ml-table-cell-color);
 		vertical-align: middle;
 	}
 
 	.ml-table--sm .ml-table__td {
-		padding: var(--ml-space-2-5) var(--ml-space-4);
+		padding: var(--ml-table-cell-padding-y-sm) var(--ml-table-cell-padding-x-sm);
 		font-size: var(--ml-text-xs);
 	}
 

package/lib/components/data-display/table/table.template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.template.d.ts","sourceRoot":"","sources":["../../../../src/components/data-display/table/table.template.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,6CA0H9C"}
+{"version":3,"file":"table.template.d.ts","sourceRoot":"","sources":["../../../../src/components/data-display/table/table.template.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,6CA+H9C"}

package/lib/components/data-display/table/table.template.js

@@ -44,6 +44,7 @@ export function tableTemplate(c) {
 							`)}
 							${repeat(c.columns, (col) => col.key, (col) => html `
 								<th
+									part="header-cell"
 									class=${classMap({
         'ml-table__th': true,
         'ml-table__th--sortable': !!col.sortable,
@@ -80,6 +81,7 @@ export function tableTemplate(c) {
         const absoluteIndex = c.startIndex + i;
         return html `
 								<tr
+									part="row"
 									class=${classMap({
             'ml-table__row': true,
             'ml-table__row--selected': c.isRowSelected(absoluteIndex)
@@ -99,10 +101,13 @@ export function tableTemplate(c) {
 										</td>
 									`)}
 									${repeat(c.columns, (col) => col.key, (col) => html `
-										<td class=${classMap({
+										<td
+											part="cell"
+											class=${classMap({
             'ml-table__td': true,
             [`ml-table__td--${col.align ?? 'left'}`]: true
-        })}>
+        })}
+										>
 											${renderCell(col, row, absoluteIndex)}
 										</td>
 									`)}

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>
 	`;