@melodicdev/components 1.6.1 → 1.6.3

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.1",
+	"version": "1.6.3",
 	"description": "Themeable UI component library built on the Melodic Framework",
 	"license": "MIT",
 	"author": "Melodic Development",