@kalyx/core 0.3.0 → 1.0.0-rc.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   DEFAULT_RANGEPICKER_LABELS: () => DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS: () => DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter: () => DateFnsAdapter,
+  civilMidnightFromUtcDay: () => civilMidnightFromUtcDay,
   formatFullDate: () => formatFullDate,
   formatInTimezone: () => formatInTimezone,
   formatMonthYear: () => formatMonthYear,
@@ -35,6 +36,7 @@ __export(index_exports, {
   getCalendarDays: () => getCalendarDays,
   getMonthName: () => getMonthName,
   getTime: () => getTime,
+  getTimeInTimezone: () => getTimeInTimezone,
   getTimezoneOffsetMinutes: () => getTimezoneOffsetMinutes,
   getWeekdayNames: () => getWeekdayNames,
   isDateDisabled: () => isDateDisabled,
@@ -46,6 +48,7 @@ __export(index_exports, {
   parseInputValue: () => parseInputValue,
   parseTimeString: () => parseTimeString,
   setTime: () => setTime,
+  setTimeInTimezone: () => setTimeInTimezone,
   startOfDayInTimezone: () => startOfDayInTimezone,
   to12Hour: () => to12Hour,
   to24Hour: () => to24Hour,
@@ -54,9 +57,116 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/adapters/date-fns.ts
+var import_date_fns2 = require("date-fns");
+
+// src/utils/timezone.ts
 var import_date_fns = require("date-fns");
+var formatterCache = /* @__PURE__ */ new Map();
+function getCachedPartsFormatter(timeZone) {
+  const key = `parts:${timeZone}`;
+  let fmt = formatterCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23"
+    });
+    formatterCache.set(key, fmt);
+  }
+  return fmt;
+}
+function partsInTimezone(utc, timeZone) {
+  const dtf = getCachedPartsFormatter(timeZone);
+  const parts = Object.fromEntries(
+    dtf.formatToParts(utc).map((p) => [p.type, p.value])
+  );
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    // Some locales/engines return '24' instead of '0' at midnight
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute),
+    second: Number(parts.second)
+  };
+}
+function formatInTimezone(iso, formatStr, timeZone) {
+  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
+  const tokens = {
+    yyyy: String(p.year),
+    MM: String(p.month).padStart(2, "0"),
+    dd: String(p.day).padStart(2, "0"),
+    HH: String(p.hour).padStart(2, "0"),
+    mm: String(p.minute).padStart(2, "0"),
+    ss: String(p.second).padStart(2, "0")
+  };
+  let result = formatStr;
+  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
+    result = result.split(token).join(value);
+  }
+  return result;
+}
+function getTimezoneOffsetMinutes(iso, timeZone) {
+  const utc = (0, import_date_fns.parseISO)(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
+}
+function startOfDayInTimezone(iso, timeZone) {
+  const utc = (0, import_date_fns.parseISO)(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
+  const midnightProbe = new Date(civilMidnightUtc).toISOString();
+  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
+  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
+}
+function isSameDayInTimezone(a, b, timeZone) {
+  const pa = partsInTimezone((0, import_date_fns.parseISO)(a), timeZone);
+  const pb = partsInTimezone((0, import_date_fns.parseISO)(b), timeZone);
+  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
+}
+function todayInTimezone(timeZone) {
+  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
+}
+function civilMidnightFromUtcDay(gridUtcIso, timeZone) {
+  const utc = (0, import_date_fns.parseISO)(gridUtcIso);
+  const probe = new Date(Date.UTC(
+    utc.getUTCFullYear(),
+    utc.getUTCMonth(),
+    utc.getUTCDate(),
+    12,
+    0,
+    0
+  )).toISOString();
+  return startOfDayInTimezone(probe, timeZone);
+}
+function getTimeInTimezone(iso, timeZone) {
+  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
+  return { hours: p.hour, minutes: p.minute, seconds: p.second };
+}
+function setTimeInTimezone(iso, partial, timeZone) {
+  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
+  const targetHours = partial.hours ?? p.hour;
+  const targetMinutes = partial.minutes ?? p.minute;
+  const targetSeconds = partial.seconds ?? p.second;
+  const civilEpoch = Date.UTC(p.year, p.month - 1, p.day, targetHours, targetMinutes, targetSeconds);
+  const probe1 = new Date(civilEpoch).toISOString();
+  const offset1 = getTimezoneOffsetMinutes(probe1, timeZone);
+  const realEpoch1 = civilEpoch - offset1 * 6e4;
+  const probe2 = new Date(realEpoch1).toISOString();
+  const offset2 = getTimezoneOffsetMinutes(probe2, timeZone);
+  const realEpoch2 = civilEpoch - offset2 * 6e4;
+  return new Date(realEpoch2).toISOString();
+}
+
+// src/adapters/date-fns.ts
 function toDate(iso) {
-  return (0, import_date_fns.parseISO)(iso);
+  return (0, import_date_fns2.parseISO)(iso);
 }
 function toISO(date) {
   return date.toISOString();
@@ -98,7 +208,10 @@ var DateFnsAdapter = {
     if (!value) return "";
     return normalize(value);
   },
-  format(iso, formatStr) {
+  format(iso, formatStr, timezone) {
+    if (timezone) {
+      return formatInTimezone(iso, formatStr, timezone);
+    }
     const d = toDate(iso);
     const tokens = {
       yyyy: String(d.getUTCFullYear()),
@@ -117,22 +230,25 @@ var DateFnsAdapter = {
     return result;
   },
   addDays(iso, n) {
-    return toISO((0, import_date_fns.addDays)(toDate(iso), n));
+    return toISO((0, import_date_fns2.addDays)(toDate(iso), n));
   },
   addMonths(iso, n) {
-    return toISO((0, import_date_fns.addMonths)(toDate(iso), n));
+    return toISO((0, import_date_fns2.addMonths)(toDate(iso), n));
   },
   addYears(iso, n) {
-    return toISO((0, import_date_fns.addYears)(toDate(iso), n));
+    return toISO((0, import_date_fns2.addYears)(toDate(iso), n));
   },
   isBefore(a, b) {
-    return (0, import_date_fns.isBefore)(toDate(a), toDate(b));
+    return (0, import_date_fns2.isBefore)(toDate(a), toDate(b));
   },
   isAfter(a, b) {
-    return (0, import_date_fns.isAfter)(toDate(a), toDate(b));
+    return (0, import_date_fns2.isAfter)(toDate(a), toDate(b));
   },
-  isSameDay(a, b) {
+  isSameDay(a, b, timezone) {
     if (!a || !b) return false;
+    if (timezone) {
+      return isSameDayInTimezone(a, b, timezone);
+    }
     const da = toDate(a);
     const db = toDate(b);
     return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth() && da.getUTCDate() === db.getUTCDate();
@@ -142,7 +258,10 @@ var DateFnsAdapter = {
     const db = toDate(b);
     return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth();
   },
-  startOfDay(iso) {
+  startOfDay(iso, timezone) {
+    if (timezone) {
+      return startOfDayInTimezone(iso, timezone);
+    }
     return toISO(utcStartOfDay(toDate(iso)));
   },
   startOfMonth(iso) {
@@ -160,14 +279,17 @@ var DateFnsAdapter = {
   now() {
     return (/* @__PURE__ */ new Date()).toISOString();
   },
-  today() {
+  today(timezone) {
+    if (timezone) {
+      return todayInTimezone(timezone);
+    }
     return toISO(utcStartOfDay(/* @__PURE__ */ new Date()));
   },
   isValid(value) {
     if (!value) return false;
     const normalized = normalize(value);
-    const date = (0, import_date_fns.parseISO)(normalized);
-    return (0, import_date_fns.isValid)(date);
+    const date = (0, import_date_fns2.parseISO)(normalized);
+    return (0, import_date_fns2.isValid)(date);
   },
   getYear(iso) {
     return toDate(iso).getUTCFullYear();
@@ -192,23 +314,24 @@ function getCalendarDays(monthISO, adapter, options = {}) {
     focusedDate,
     disabled = [],
     range,
-    rangeHover
+    rangeHover,
+    timezone
   } = options;
-  const todayISO = today ?? adapter.today();
+  const todayISO = today ?? adapter.today(timezone);
   const monthStart = adapter.startOfMonth(monthISO);
   const gridStart = adapter.startOfWeek(monthStart, weekStartsOn);
-  const normalizedRange = normalizeRangeForDisplay(range, rangeHover, adapter);
+  const normalizedRange = normalizeRangeForDisplay(range, rangeHover, adapter, timezone);
   const weeks = [];
   let current = gridStart;
   for (let week = 0; week < 6; week++) {
     const days = [];
     for (let day = 0; day < 7; day++) {
       const isCurrentMonth = adapter.isSameMonth(current, monthISO);
-      const isTodayDate = adapter.isSameDay(current, todayISO);
-      const isSelected_ = selected ? adapter.isSameDay(current, selected) : false;
-      const isFocused_ = focusedDate ? adapter.isSameDay(current, focusedDate) : false;
+      const isTodayDate = adapter.isSameDay(current, todayISO, timezone);
+      const isSelected_ = selected ? adapter.isSameDay(current, selected, timezone) : false;
+      const isFocused_ = focusedDate ? adapter.isSameDay(current, focusedDate, timezone) : false;
       const isDisabled_ = isDateDisabled(current, disabled, adapter);
-      const rangeFlags = computeRangeFlags(current, normalizedRange, adapter);
+      const rangeFlags = computeRangeFlags(current, normalizedRange, adapter, timezone);
       days.push({
         isoString: current,
         dayNumber: adapter.getDate(current),
@@ -228,7 +351,7 @@ function getCalendarDays(monthISO, adapter, options = {}) {
   }
   return weeks;
 }
-function normalizeRangeForDisplay(range, hover, adapter) {
+function normalizeRangeForDisplay(range, hover, adapter, _timezone) {
   if (!range) return { start: null, end: null };
   const { start, end } = range;
   if (start && end) {
@@ -248,16 +371,16 @@ function normalizeRangeForDisplay(range, hover, adapter) {
   }
   return { start: null, end: null };
 }
-function computeRangeFlags(iso, range, adapter) {
+function computeRangeFlags(iso, range, adapter, timezone) {
   const { start, end } = range;
   if (!start) {
     return { isRangeStart: false, isRangeEnd: false, isInRange: false };
   }
-  const isRangeStart = adapter.isSameDay(iso, start);
+  const isRangeStart = adapter.isSameDay(iso, start, timezone);
   if (!end) {
     return { isRangeStart, isRangeEnd: false, isInRange: false };
   }
-  const isRangeEnd = adapter.isSameDay(iso, end);
+  const isRangeEnd = adapter.isSameDay(iso, end, timezone);
   const isInRange = !isRangeStart && !isRangeEnd && adapter.isAfter(iso, start) && adapter.isBefore(iso, end);
   return { isRangeStart, isRangeEnd, isInRange };
 }
@@ -393,13 +516,13 @@ function formatTimeFromISO(iso, format) {
 }
 
 // src/utils/locale.ts
-var formatterCache = /* @__PURE__ */ new Map();
+var formatterCache2 = /* @__PURE__ */ new Map();
 function getCachedFormatter(locale, options) {
   const key = `${locale}:${JSON.stringify(options)}`;
-  let fmt = formatterCache.get(key);
+  let fmt = formatterCache2.get(key);
   if (!fmt) {
     fmt = new Intl.DateTimeFormat(locale, options);
-    formatterCache.set(key, fmt);
+    formatterCache2.set(key, fmt);
   }
   return fmt;
 }
@@ -444,81 +567,6 @@ function formatFullDate(iso, locale = "en-US") {
   }).format(date);
 }
 
-// src/utils/timezone.ts
-var import_date_fns2 = require("date-fns");
-var formatterCache2 = /* @__PURE__ */ new Map();
-function getCachedPartsFormatter(timeZone) {
-  const key = `parts:${timeZone}`;
-  let fmt = formatterCache2.get(key);
-  if (!fmt) {
-    fmt = new Intl.DateTimeFormat("en-US", {
-      timeZone,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      hourCycle: "h23"
-    });
-    formatterCache2.set(key, fmt);
-  }
-  return fmt;
-}
-function partsInTimezone(utc, timeZone) {
-  const dtf = getCachedPartsFormatter(timeZone);
-  const parts = Object.fromEntries(
-    dtf.formatToParts(utc).map((p) => [p.type, p.value])
-  );
-  return {
-    year: Number(parts.year),
-    month: Number(parts.month),
-    day: Number(parts.day),
-    // Some locales/engines return '24' instead of '0' at midnight
-    hour: parts.hour === "24" ? 0 : Number(parts.hour),
-    minute: Number(parts.minute),
-    second: Number(parts.second)
-  };
-}
-function formatInTimezone(iso, formatStr, timeZone) {
-  const p = partsInTimezone((0, import_date_fns2.parseISO)(iso), timeZone);
-  const tokens = {
-    yyyy: String(p.year),
-    MM: String(p.month).padStart(2, "0"),
-    dd: String(p.day).padStart(2, "0"),
-    HH: String(p.hour).padStart(2, "0"),
-    mm: String(p.minute).padStart(2, "0"),
-    ss: String(p.second).padStart(2, "0")
-  };
-  let result = formatStr;
-  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
-    result = result.split(token).join(value);
-  }
-  return result;
-}
-function getTimezoneOffsetMinutes(iso, timeZone) {
-  const utc = (0, import_date_fns2.parseISO)(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
-  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
-}
-function startOfDayInTimezone(iso, timeZone) {
-  const utc = (0, import_date_fns2.parseISO)(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
-  const midnightProbe = new Date(civilMidnightUtc).toISOString();
-  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
-  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
-}
-function isSameDayInTimezone(a, b, timeZone) {
-  const pa = partsInTimezone((0, import_date_fns2.parseISO)(a), timeZone);
-  const pb = partsInTimezone((0, import_date_fns2.parseISO)(b), timeZone);
-  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
-}
-function todayInTimezone(timeZone) {
-  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
-}
-
 // src/utils/labels.ts
 var DEFAULT_DATEPICKER_LABELS = {
   triggerOpen: "Open calendar",
@@ -558,6 +606,7 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter,
+  civilMidnightFromUtcDay,
   formatFullDate,
   formatInTimezone,
   formatMonthYear,
@@ -568,6 +617,7 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimeInTimezone,
   getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
@@ -579,6 +629,7 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   parseInputValue,
   parseTimeString,
   setTime,
+  setTimeInTimezone,
   startOfDayInTimezone,
   to12Hour,
   to24Hour,

package/dist/index.d.cts

@@ -102,6 +102,12 @@ interface CalendarOptions {
     range?: DateRange | null;
     /** Currently hovered date (for RangePicker preview) */
     rangeHover?: ISODateString | null;
+    /**
+     * IANA timezone. When set, `isSameDay` comparisons for today/selected/range flags are
+     * evaluated in this zone — required when the picker stores values in display-tz civil
+     * midnight form while the grid iterates in UTC.
+     */
+    timezone?: string;
 }
 
 /**
@@ -306,6 +312,52 @@ declare function isSameDayInTimezone(a: ISODateString, b: ISODateString, timeZon
  * timezone rather than the server's local clock.
  */
 declare function todayInTimezone(timeZone: string): ISODateString;
+/**
+ * Converts a UTC-midnight ISO (as produced by the default calendar grid iteration) into the
+ * civil midnight of the same calendar day in `timeZone`.
+ *
+ * This is the bridge used by DatePicker/RangePicker when `displayTimezone` is set: the grid
+ * iterates in UTC, so a cell's `isoString` is `YYYY-MM-DDT00:00:00.000Z`. When the user clicks
+ * that cell we want to emit an ISO representing the same civil day's midnight in the display
+ * timezone. A probe at noon UTC is used so the target civil day is unambiguous across any zone.
+ *
+ * @example
+ * civilMidnightFromUtcDay('2026-01-15T00:00:00.000Z', 'Asia/Seoul');
+ * // → '2026-01-14T15:00:00.000Z'  (Seoul Jan 15 00:00 = UTC Jan 14 15:00)
+ */
+declare function civilMidnightFromUtcDay(gridUtcIso: ISODateString, timeZone: string): ISODateString;
+/**
+ * Extracts the time-of-day (hours / minutes / seconds) of a UTC instant as observed in
+ * `timeZone`. The result differs from reading UTC hours when the zone has a non-zero offset.
+ *
+ * @example
+ * getTimeInTimezone('2026-01-15T00:00:00.000Z', 'Asia/Seoul');
+ * // → { hours: 9, minutes: 0, seconds: 0 }  (Seoul is UTC+9)
+ */
+declare function getTimeInTimezone(iso: ISODateString, timeZone: string): {
+    hours: number;
+    minutes: number;
+    seconds: number;
+};
+/**
+ * Returns a new ISO UTC string where the civil date in `timeZone` is preserved and the time
+ * portion is replaced according to `partial` (as observed in that same timezone). Undefined
+ * fields keep their current value.
+ *
+ * Implementation note: the civil target (Y,M,D,H,m,s) is first mapped to a UTC epoch as if
+ * the wall-clock reading lived in UTC; then we subtract the timezone offset at that instant
+ * to recover the real UTC instant. The offset is refined once to absorb DST transitions.
+ *
+ * @example
+ * // In Asia/Seoul (UTC+9): set the hour to 10
+ * setTimeInTimezone('2026-01-15T00:00:00.000Z', { hours: 10 }, 'Asia/Seoul');
+ * // → '2026-01-15T01:00:00.000Z'   (Seoul Jan 15 10:00 = UTC 01:00)
+ */
+declare function setTimeInTimezone(iso: ISODateString, partial: {
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}, timeZone: string): ISODateString;
 
 /**
  * Default English labels for ARIA attributes and accessible text.
@@ -345,4 +397,4 @@ declare const DEFAULT_RANGEPICKER_LABELS: RangePickerLabels;
 declare const DEFAULT_TIMEPICKER_LABELS: TimePickerLabels;
 declare const DEFAULT_DATETIMEPICKER_LABELS: DateTimePickerLabels;
 
-export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, DateFnsAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };
+export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, DateFnsAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, civilMidnightFromUtcDay, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimeInTimezone, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, setTimeInTimezone, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };

package/dist/index.d.ts

@@ -102,6 +102,12 @@ interface CalendarOptions {
     range?: DateRange | null;
     /** Currently hovered date (for RangePicker preview) */
     rangeHover?: ISODateString | null;
+    /**
+     * IANA timezone. When set, `isSameDay` comparisons for today/selected/range flags are
+     * evaluated in this zone — required when the picker stores values in display-tz civil
+     * midnight form while the grid iterates in UTC.
+     */
+    timezone?: string;
 }
 
 /**
@@ -306,6 +312,52 @@ declare function isSameDayInTimezone(a: ISODateString, b: ISODateString, timeZon
  * timezone rather than the server's local clock.
  */
 declare function todayInTimezone(timeZone: string): ISODateString;
+/**
+ * Converts a UTC-midnight ISO (as produced by the default calendar grid iteration) into the
+ * civil midnight of the same calendar day in `timeZone`.
+ *
+ * This is the bridge used by DatePicker/RangePicker when `displayTimezone` is set: the grid
+ * iterates in UTC, so a cell's `isoString` is `YYYY-MM-DDT00:00:00.000Z`. When the user clicks
+ * that cell we want to emit an ISO representing the same civil day's midnight in the display
+ * timezone. A probe at noon UTC is used so the target civil day is unambiguous across any zone.
+ *
+ * @example
+ * civilMidnightFromUtcDay('2026-01-15T00:00:00.000Z', 'Asia/Seoul');
+ * // → '2026-01-14T15:00:00.000Z'  (Seoul Jan 15 00:00 = UTC Jan 14 15:00)
+ */
+declare function civilMidnightFromUtcDay(gridUtcIso: ISODateString, timeZone: string): ISODateString;
+/**
+ * Extracts the time-of-day (hours / minutes / seconds) of a UTC instant as observed in
+ * `timeZone`. The result differs from reading UTC hours when the zone has a non-zero offset.
+ *
+ * @example
+ * getTimeInTimezone('2026-01-15T00:00:00.000Z', 'Asia/Seoul');
+ * // → { hours: 9, minutes: 0, seconds: 0 }  (Seoul is UTC+9)
+ */
+declare function getTimeInTimezone(iso: ISODateString, timeZone: string): {
+    hours: number;
+    minutes: number;
+    seconds: number;
+};
+/**
+ * Returns a new ISO UTC string where the civil date in `timeZone` is preserved and the time
+ * portion is replaced according to `partial` (as observed in that same timezone). Undefined
+ * fields keep their current value.
+ *
+ * Implementation note: the civil target (Y,M,D,H,m,s) is first mapped to a UTC epoch as if
+ * the wall-clock reading lived in UTC; then we subtract the timezone offset at that instant
+ * to recover the real UTC instant. The offset is refined once to absorb DST transitions.
+ *
+ * @example
+ * // In Asia/Seoul (UTC+9): set the hour to 10
+ * setTimeInTimezone('2026-01-15T00:00:00.000Z', { hours: 10 }, 'Asia/Seoul');
+ * // → '2026-01-15T01:00:00.000Z'   (Seoul Jan 15 10:00 = UTC 01:00)
+ */
+declare function setTimeInTimezone(iso: ISODateString, partial: {
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}, timeZone: string): ISODateString;
 
 /**
  * Default English labels for ARIA attributes and accessible text.
@@ -345,4 +397,4 @@ declare const DEFAULT_RANGEPICKER_LABELS: RangePickerLabels;
 declare const DEFAULT_TIMEPICKER_LABELS: TimePickerLabels;
 declare const DEFAULT_DATETIMEPICKER_LABELS: DateTimePickerLabels;
 
-export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, DateFnsAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };
+export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, DateFnsAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, civilMidnightFromUtcDay, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimeInTimezone, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, setTimeInTimezone, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/adapters/date-fns.ts
 import {
-  parseISO,
+  parseISO as parseISO2,
   addDays as dfAddDays,
   addMonths as dfAddMonths,
   addYears as dfAddYears,
@@ -8,8 +8,115 @@ import {
   isAfter as dfIsAfter,
   isValid as dfIsValid
 } from "date-fns";
+
+// src/utils/timezone.ts
+import { parseISO } from "date-fns";
+var formatterCache = /* @__PURE__ */ new Map();
+function getCachedPartsFormatter(timeZone) {
+  const key = `parts:${timeZone}`;
+  let fmt = formatterCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23"
+    });
+    formatterCache.set(key, fmt);
+  }
+  return fmt;
+}
+function partsInTimezone(utc, timeZone) {
+  const dtf = getCachedPartsFormatter(timeZone);
+  const parts = Object.fromEntries(
+    dtf.formatToParts(utc).map((p) => [p.type, p.value])
+  );
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    // Some locales/engines return '24' instead of '0' at midnight
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute),
+    second: Number(parts.second)
+  };
+}
+function formatInTimezone(iso, formatStr, timeZone) {
+  const p = partsInTimezone(parseISO(iso), timeZone);
+  const tokens = {
+    yyyy: String(p.year),
+    MM: String(p.month).padStart(2, "0"),
+    dd: String(p.day).padStart(2, "0"),
+    HH: String(p.hour).padStart(2, "0"),
+    mm: String(p.minute).padStart(2, "0"),
+    ss: String(p.second).padStart(2, "0")
+  };
+  let result = formatStr;
+  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
+    result = result.split(token).join(value);
+  }
+  return result;
+}
+function getTimezoneOffsetMinutes(iso, timeZone) {
+  const utc = parseISO(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
+}
+function startOfDayInTimezone(iso, timeZone) {
+  const utc = parseISO(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
+  const midnightProbe = new Date(civilMidnightUtc).toISOString();
+  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
+  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
+}
+function isSameDayInTimezone(a, b, timeZone) {
+  const pa = partsInTimezone(parseISO(a), timeZone);
+  const pb = partsInTimezone(parseISO(b), timeZone);
+  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
+}
+function todayInTimezone(timeZone) {
+  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
+}
+function civilMidnightFromUtcDay(gridUtcIso, timeZone) {
+  const utc = parseISO(gridUtcIso);
+  const probe = new Date(Date.UTC(
+    utc.getUTCFullYear(),
+    utc.getUTCMonth(),
+    utc.getUTCDate(),
+    12,
+    0,
+    0
+  )).toISOString();
+  return startOfDayInTimezone(probe, timeZone);
+}
+function getTimeInTimezone(iso, timeZone) {
+  const p = partsInTimezone(parseISO(iso), timeZone);
+  return { hours: p.hour, minutes: p.minute, seconds: p.second };
+}
+function setTimeInTimezone(iso, partial, timeZone) {
+  const p = partsInTimezone(parseISO(iso), timeZone);
+  const targetHours = partial.hours ?? p.hour;
+  const targetMinutes = partial.minutes ?? p.minute;
+  const targetSeconds = partial.seconds ?? p.second;
+  const civilEpoch = Date.UTC(p.year, p.month - 1, p.day, targetHours, targetMinutes, targetSeconds);
+  const probe1 = new Date(civilEpoch).toISOString();
+  const offset1 = getTimezoneOffsetMinutes(probe1, timeZone);
+  const realEpoch1 = civilEpoch - offset1 * 6e4;
+  const probe2 = new Date(realEpoch1).toISOString();
+  const offset2 = getTimezoneOffsetMinutes(probe2, timeZone);
+  const realEpoch2 = civilEpoch - offset2 * 6e4;
+  return new Date(realEpoch2).toISOString();
+}
+
+// src/adapters/date-fns.ts
 function toDate(iso) {
-  return parseISO(iso);
+  return parseISO2(iso);
 }
 function toISO(date) {
   return date.toISOString();
@@ -51,7 +158,10 @@ var DateFnsAdapter = {
     if (!value) return "";
     return normalize(value);
   },
-  format(iso, formatStr) {
+  format(iso, formatStr, timezone) {
+    if (timezone) {
+      return formatInTimezone(iso, formatStr, timezone);
+    }
     const d = toDate(iso);
     const tokens = {
       yyyy: String(d.getUTCFullYear()),
@@ -84,8 +194,11 @@ var DateFnsAdapter = {
   isAfter(a, b) {
     return dfIsAfter(toDate(a), toDate(b));
   },
-  isSameDay(a, b) {
+  isSameDay(a, b, timezone) {
     if (!a || !b) return false;
+    if (timezone) {
+      return isSameDayInTimezone(a, b, timezone);
+    }
     const da = toDate(a);
     const db = toDate(b);
     return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth() && da.getUTCDate() === db.getUTCDate();
@@ -95,7 +208,10 @@ var DateFnsAdapter = {
     const db = toDate(b);
     return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth();
   },
-  startOfDay(iso) {
+  startOfDay(iso, timezone) {
+    if (timezone) {
+      return startOfDayInTimezone(iso, timezone);
+    }
     return toISO(utcStartOfDay(toDate(iso)));
   },
   startOfMonth(iso) {
@@ -113,13 +229,16 @@ var DateFnsAdapter = {
   now() {
     return (/* @__PURE__ */ new Date()).toISOString();
   },
-  today() {
+  today(timezone) {
+    if (timezone) {
+      return todayInTimezone(timezone);
+    }
     return toISO(utcStartOfDay(/* @__PURE__ */ new Date()));
   },
   isValid(value) {
     if (!value) return false;
     const normalized = normalize(value);
-    const date = parseISO(normalized);
+    const date = parseISO2(normalized);
     return dfIsValid(date);
   },
   getYear(iso) {
@@ -145,23 +264,24 @@ function getCalendarDays(monthISO, adapter, options = {}) {
     focusedDate,
     disabled = [],
     range,
-    rangeHover
+    rangeHover,
+    timezone
   } = options;
-  const todayISO = today ?? adapter.today();
+  const todayISO = today ?? adapter.today(timezone);
   const monthStart = adapter.startOfMonth(monthISO);
   const gridStart = adapter.startOfWeek(monthStart, weekStartsOn);
-  const normalizedRange = normalizeRangeForDisplay(range, rangeHover, adapter);
+  const normalizedRange = normalizeRangeForDisplay(range, rangeHover, adapter, timezone);
   const weeks = [];
   let current = gridStart;
   for (let week = 0; week < 6; week++) {
     const days = [];
     for (let day = 0; day < 7; day++) {
       const isCurrentMonth = adapter.isSameMonth(current, monthISO);
-      const isTodayDate = adapter.isSameDay(current, todayISO);
-      const isSelected_ = selected ? adapter.isSameDay(current, selected) : false;
-      const isFocused_ = focusedDate ? adapter.isSameDay(current, focusedDate) : false;
+      const isTodayDate = adapter.isSameDay(current, todayISO, timezone);
+      const isSelected_ = selected ? adapter.isSameDay(current, selected, timezone) : false;
+      const isFocused_ = focusedDate ? adapter.isSameDay(current, focusedDate, timezone) : false;
       const isDisabled_ = isDateDisabled(current, disabled, adapter);
-      const rangeFlags = computeRangeFlags(current, normalizedRange, adapter);
+      const rangeFlags = computeRangeFlags(current, normalizedRange, adapter, timezone);
       days.push({
         isoString: current,
         dayNumber: adapter.getDate(current),
@@ -181,7 +301,7 @@ function getCalendarDays(monthISO, adapter, options = {}) {
   }
   return weeks;
 }
-function normalizeRangeForDisplay(range, hover, adapter) {
+function normalizeRangeForDisplay(range, hover, adapter, _timezone) {
   if (!range) return { start: null, end: null };
   const { start, end } = range;
   if (start && end) {
@@ -201,16 +321,16 @@ function normalizeRangeForDisplay(range, hover, adapter) {
   }
   return { start: null, end: null };
 }
-function computeRangeFlags(iso, range, adapter) {
+function computeRangeFlags(iso, range, adapter, timezone) {
   const { start, end } = range;
   if (!start) {
     return { isRangeStart: false, isRangeEnd: false, isInRange: false };
   }
-  const isRangeStart = adapter.isSameDay(iso, start);
+  const isRangeStart = adapter.isSameDay(iso, start, timezone);
   if (!end) {
     return { isRangeStart, isRangeEnd: false, isInRange: false };
   }
-  const isRangeEnd = adapter.isSameDay(iso, end);
+  const isRangeEnd = adapter.isSameDay(iso, end, timezone);
   const isInRange = !isRangeStart && !isRangeEnd && adapter.isAfter(iso, start) && adapter.isBefore(iso, end);
   return { isRangeStart, isRangeEnd, isInRange };
 }
@@ -346,13 +466,13 @@ function formatTimeFromISO(iso, format) {
 }
 
 // src/utils/locale.ts
-var formatterCache = /* @__PURE__ */ new Map();
+var formatterCache2 = /* @__PURE__ */ new Map();
 function getCachedFormatter(locale, options) {
   const key = `${locale}:${JSON.stringify(options)}`;
-  let fmt = formatterCache.get(key);
+  let fmt = formatterCache2.get(key);
   if (!fmt) {
     fmt = new Intl.DateTimeFormat(locale, options);
-    formatterCache.set(key, fmt);
+    formatterCache2.set(key, fmt);
   }
   return fmt;
 }
@@ -397,81 +517,6 @@ function formatFullDate(iso, locale = "en-US") {
   }).format(date);
 }
 
-// src/utils/timezone.ts
-import { parseISO as parseISO2 } from "date-fns";
-var formatterCache2 = /* @__PURE__ */ new Map();
-function getCachedPartsFormatter(timeZone) {
-  const key = `parts:${timeZone}`;
-  let fmt = formatterCache2.get(key);
-  if (!fmt) {
-    fmt = new Intl.DateTimeFormat("en-US", {
-      timeZone,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      hourCycle: "h23"
-    });
-    formatterCache2.set(key, fmt);
-  }
-  return fmt;
-}
-function partsInTimezone(utc, timeZone) {
-  const dtf = getCachedPartsFormatter(timeZone);
-  const parts = Object.fromEntries(
-    dtf.formatToParts(utc).map((p) => [p.type, p.value])
-  );
-  return {
-    year: Number(parts.year),
-    month: Number(parts.month),
-    day: Number(parts.day),
-    // Some locales/engines return '24' instead of '0' at midnight
-    hour: parts.hour === "24" ? 0 : Number(parts.hour),
-    minute: Number(parts.minute),
-    second: Number(parts.second)
-  };
-}
-function formatInTimezone(iso, formatStr, timeZone) {
-  const p = partsInTimezone(parseISO2(iso), timeZone);
-  const tokens = {
-    yyyy: String(p.year),
-    MM: String(p.month).padStart(2, "0"),
-    dd: String(p.day).padStart(2, "0"),
-    HH: String(p.hour).padStart(2, "0"),
-    mm: String(p.minute).padStart(2, "0"),
-    ss: String(p.second).padStart(2, "0")
-  };
-  let result = formatStr;
-  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
-    result = result.split(token).join(value);
-  }
-  return result;
-}
-function getTimezoneOffsetMinutes(iso, timeZone) {
-  const utc = parseISO2(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
-  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
-}
-function startOfDayInTimezone(iso, timeZone) {
-  const utc = parseISO2(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
-  const midnightProbe = new Date(civilMidnightUtc).toISOString();
-  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
-  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
-}
-function isSameDayInTimezone(a, b, timeZone) {
-  const pa = partsInTimezone(parseISO2(a), timeZone);
-  const pb = partsInTimezone(parseISO2(b), timeZone);
-  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
-}
-function todayInTimezone(timeZone) {
-  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
-}
-
 // src/utils/labels.ts
 var DEFAULT_DATEPICKER_LABELS = {
   triggerOpen: "Open calendar",
@@ -510,6 +555,7 @@ export {
   DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter,
+  civilMidnightFromUtcDay,
   formatFullDate,
   formatInTimezone,
   formatMonthYear,
@@ -520,6 +566,7 @@ export {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimeInTimezone,
   getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
@@ -531,6 +578,7 @@ export {
   parseInputValue,
   parseTimeString,
   setTime,
+  setTimeInTimezone,
   startOfDayInTimezone,
   to12Hour,
   to24Hour,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kalyx/core",
-  "version": "0.3.0",
-  "description": "Kalyx core — platform-agnostic date logic",
+  "version": "1.0.0-rc.0",
+  "description": "Kalyx core — platform-agnostic date logic, IANA timezone helpers, and the DateAdapter contract used by @kalyx/react",
   "license": "MIT",
   "author": "jiji-hoon96",
   "homepage": "https://github.com/jiji-hoon96/kalyx#readme",
@@ -18,11 +18,14 @@
     "datepicker",
     "calendar",
     "timezone",
+    "iana",
+    "dst",
     "iso8601",
     "utc",
     "date-fns"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",