@kalyx/core 0.2.2 → 0.4.0

package/dist/index.cjs

@@ -20,8 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_DATEPICKER_LABELS: () => DEFAULT_DATEPICKER_LABELS,
+  DEFAULT_DATETIMEPICKER_LABELS: () => DEFAULT_DATETIMEPICKER_LABELS,
+  DEFAULT_RANGEPICKER_LABELS: () => DEFAULT_RANGEPICKER_LABELS,
+  DEFAULT_TIMEPICKER_LABELS: () => DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter: () => DateFnsAdapter,
+  civilMidnightFromUtcDay: () => civilMidnightFromUtcDay,
   formatFullDate: () => formatFullDate,
+  formatInTimezone: () => formatInTimezone,
   formatMonthYear: () => formatMonthYear,
   formatTimeFromISO: () => formatTimeFromISO,
   formatTimeString: () => formatTimeString,
@@ -30,8 +36,11 @@ __export(index_exports, {
   getCalendarDays: () => getCalendarDays,
   getMonthName: () => getMonthName,
   getTime: () => getTime,
+  getTimeInTimezone: () => getTimeInTimezone,
+  getTimezoneOffsetMinutes: () => getTimezoneOffsetMinutes,
   getWeekdayNames: () => getWeekdayNames,
   isDateDisabled: () => isDateDisabled,
+  isSameDayInTimezone: () => isSameDayInTimezone,
   isSameTime: () => isSameTime,
   maxDate: () => maxDate,
   minDate: () => minDate,
@@ -39,15 +48,125 @@ __export(index_exports, {
   parseInputValue: () => parseInputValue,
   parseTimeString: () => parseTimeString,
   setTime: () => setTime,
+  setTimeInTimezone: () => setTimeInTimezone,
+  startOfDayInTimezone: () => startOfDayInTimezone,
   to12Hour: () => to12Hour,
-  to24Hour: () => to24Hour
+  to24Hour: () => to24Hour,
+  todayInTimezone: () => todayInTimezone
 });
 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();
@@ -89,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()),
@@ -108,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();
@@ -133,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) {
@@ -151,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();
@@ -183,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),
@@ -219,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) {
@@ -239,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 };
 }
@@ -275,14 +407,14 @@ function maxDate(a, b, adapter) {
 
 // src/utils/date.ts
 var ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
-var ISO_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+var ISO_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 function normalizeISO(value) {
   if (!value) return "";
   if (ISO_DATETIME_REGEX.test(value)) return value;
   if (ISO_DATE_REGEX.test(value)) return `${value}T00:00:00.000Z`;
   return value;
 }
-function parseInputValue(input, format, adapter) {
+function parseInputValue(input, adapter) {
   if (!input.trim()) return null;
   const cleaned = input.replace(/\//g, "-").trim();
   if (ISO_DATE_REGEX.test(cleaned)) {
@@ -357,8 +489,8 @@ function generateHours(format = "24h") {
   return Array.from({ length: 24 }, (_, i) => i);
 }
 function generateMinutes(step = 1) {
-  if (step < 1 || step > 60) {
-    throw new Error(`[generateMinutes] step must be between 1 and 60, got ${step}`);
+  if (step < 1 || step > 30) {
+    throw new Error(`[generateMinutes] step must be between 1 and 30, got ${step}`);
   }
   const result = [];
   for (let i = 0; i < 60; i += step) {
@@ -369,7 +501,7 @@ function generateMinutes(step = 1) {
 function isSameTime(a, b) {
   return a.hours === b.hours && a.minutes === b.minutes && a.seconds === b.seconds;
 }
-function formatTimeFromISO(iso, format, _adapter) {
+function formatTimeFromISO(iso, format) {
   const time = getTime(iso);
   if (format === "h:mm a" || format === "h:mm:ss a") {
     const { hours12, period } = to12Hour(time.hours);
@@ -384,30 +516,35 @@ function formatTimeFromISO(iso, format, _adapter) {
 }
 
 // src/utils/locale.ts
+var formatterCache2 = /* @__PURE__ */ new Map();
+function getCachedFormatter(locale, options) {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let fmt = formatterCache2.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options);
+    formatterCache2.set(key, fmt);
+  }
+  return fmt;
+}
+var REFERENCE_YEAR = 2026;
 function getMonthName(month, locale = "en-US") {
-  const date = new Date(Date.UTC(2026, month, 1));
-  return new Intl.DateTimeFormat(locale, { month: "long", timeZone: "UTC" }).format(date);
+  const date = new Date(Date.UTC(REFERENCE_YEAR, month, 1));
+  return getCachedFormatter(locale, { month: "long", timeZone: "UTC" }).format(date);
 }
 function formatMonthYear(year, month, locale = "en-US") {
   const date = new Date(Date.UTC(year, month, 1));
-  return new Intl.DateTimeFormat(locale, {
+  return getCachedFormatter(locale, {
     year: "numeric",
     month: "long",
     timeZone: "UTC"
   }).format(date);
 }
 function getWeekdayNames(locale = "en-US", weekStartsOn = 0) {
-  const shortFormatter = new Intl.DateTimeFormat(locale, {
-    weekday: "short",
-    timeZone: "UTC"
-  });
-  const fullFormatter = new Intl.DateTimeFormat(locale, {
-    weekday: "long",
-    timeZone: "UTC"
-  });
+  const shortFormatter = getCachedFormatter(locale, { weekday: "short", timeZone: "UTC" });
+  const fullFormatter = getCachedFormatter(locale, { weekday: "long", timeZone: "UTC" });
   const days = [];
   for (let i = 0; i < 7; i++) {
-    const date = new Date(Date.UTC(2026, 0, 4 + i));
+    const date = new Date(Date.UTC(REFERENCE_YEAR, 0, 4 + i));
     days.push({
       short: shortFormatter.format(date),
       full: fullFormatter.format(date)
@@ -421,7 +558,7 @@ function getWeekdayNames(locale = "en-US", weekStartsOn = 0) {
 }
 function formatFullDate(iso, locale = "en-US") {
   const date = new Date(iso);
-  return new Intl.DateTimeFormat(locale, {
+  return getCachedFormatter(locale, {
     year: "numeric",
     month: "long",
     day: "numeric",
@@ -429,10 +566,49 @@ function formatFullDate(iso, locale = "en-US") {
     timeZone: "UTC"
   }).format(date);
 }
+
+// src/utils/labels.ts
+var DEFAULT_DATEPICKER_LABELS = {
+  triggerOpen: "Open calendar",
+  triggerClose: "Close calendar",
+  popoverLabel: "Choose date",
+  prevMonth: "Previous month",
+  nextMonth: "Next month",
+  prevYear: "Previous year",
+  nextYear: "Next year",
+  prevDecade: "Previous decade",
+  nextDecade: "Next decade"
+};
+var DEFAULT_RANGEPICKER_LABELS = {
+  ...DEFAULT_DATEPICKER_LABELS,
+  popoverLabel: "Choose date range",
+  startInput: "Start date",
+  endInput: "End date",
+  presetsGroup: "Date range presets"
+};
+var DEFAULT_TIMEPICKER_LABELS = {
+  timeInput: "Time",
+  hourList: "Hour",
+  minuteList: "Minute",
+  amPmToggle: "AM/PM",
+  hourOption: (hour) => `${hour} hours`,
+  minuteOption: (minute) => `${minute} minutes`
+};
+var DEFAULT_DATETIMEPICKER_LABELS = {
+  ...DEFAULT_DATEPICKER_LABELS,
+  ...DEFAULT_TIMEPICKER_LABELS,
+  dateTimeInput: "Date and time"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_DATEPICKER_LABELS,
+  DEFAULT_DATETIMEPICKER_LABELS,
+  DEFAULT_RANGEPICKER_LABELS,
+  DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter,
+  civilMidnightFromUtcDay,
   formatFullDate,
+  formatInTimezone,
   formatMonthYear,
   formatTimeFromISO,
   formatTimeString,
@@ -441,8 +617,11 @@ function formatFullDate(iso, locale = "en-US") {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimeInTimezone,
+  getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
+  isSameDayInTimezone,
   isSameTime,
   maxDate,
   minDate,
@@ -450,6 +629,9 @@ function formatFullDate(iso, locale = "en-US") {
   parseInputValue,
   parseTimeString,
   setTime,
+  setTimeInTimezone,
+  startOfDayInTimezone,
   to12Hour,
-  to24Hour
+  to24Hour,
+  todayInTimezone
 });

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;
 }
 
 /**
@@ -156,13 +162,16 @@ declare function maxDate(a: ISODateString, b: ISODateString, adapter: DateAdapte
 /**
  * Normalizes a date string to ISO 8601 UTC form.
  * "2026-01-15" → "2026-01-15T00:00:00.000Z"
+ *
+ * Full datetime strings must include a timezone suffix (Z or ±HH:MM).
+ * Strings without a timezone suffix are treated as-is (not matched as datetime).
  */
 declare function normalizeISO(value: string): string;
 /**
  * Parses user input text into an ISO string.
  * Returns null on failure.
  */
-declare function parseInputValue(input: string, format: string, adapter: DateAdapter): string | null;
+declare function parseInputValue(input: string, adapter: DateAdapter): string | null;
 
 /** Time-of-day value (24-hour clock) */
 interface TimeValue {
@@ -219,7 +228,7 @@ declare function isSameTime(a: TimeValue, b: TimeValue): boolean;
  * Formats an ISO datetime as a time string (UTC based).
  * Accepts an adapter for API consistency.
  */
-declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a', _adapter?: DateAdapter): string;
+declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a'): string;
 
 interface WeekdayInfo {
     /** Short name (e.g. "Su", "일") */
@@ -252,4 +261,140 @@ declare function getWeekdayNames(locale?: string, weekStartsOn?: WeekStartsOn):
  */
 declare function formatFullDate(iso: string, locale?: string): string;
 
-export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, type DateAdapter, DateFnsAdapter, type DateRange, type DisabledRule, type ISODateString, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getWeekdayNames, isDateDisabled, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, to12Hour, to24Hour };
+/**
+ * Format a UTC ISO string for display in a specific IANA timezone.
+ * Handles DST transitions correctly. Supports a small set of tokens: `yyyy MM dd HH mm ss`.
+ *
+ * @param iso - UTC ISO 8601 string
+ * @param formatStr - token string (e.g. `"yyyy-MM-dd HH:mm"`)
+ * @param timeZone - IANA zone (e.g. `"America/New_York"`)
+ *
+ * @example
+ * formatInTimezone('2026-03-08T07:30:00.000Z', 'yyyy-MM-dd HH:mm', 'America/New_York');
+ * // → '2026-03-08 03:30'   (post spring-forward EDT)
+ */
+declare function formatInTimezone(iso: ISODateString, formatStr: string, timeZone: string): string;
+/**
+ * UTC offset (minutes east of UTC) at a given UTC instant, as applied by the given timezone.
+ * The offset may differ on either side of a DST transition.
+ *
+ * @example
+ * getTimezoneOffsetMinutes('2026-03-08T06:00:00.000Z', 'America/New_York'); // -300 (EST, UTC-5)
+ * getTimezoneOffsetMinutes('2026-03-08T07:00:00.000Z', 'America/New_York'); // -240 (EDT, UTC-4)
+ * getTimezoneOffsetMinutes('2026-01-15T12:00:00.000Z', 'Asia/Seoul');       //  540 (UTC+9)
+ */
+declare function getTimezoneOffsetMinutes(iso: ISODateString, timeZone: string): number;
+/**
+ * Midnight of the civil date (as observed in `timeZone`) returned as a UTC ISO string.
+ *
+ * Across DST transitions this is the correct way to compute "start of day" — the offset
+ * changes, so the UTC instant of midnight differs before and after the transition.
+ *
+ * @example
+ * startOfDayInTimezone('2026-03-08T12:00:00.000Z', 'America/New_York'); // '2026-03-08T05:00:00.000Z' (EST)
+ * startOfDayInTimezone('2026-03-09T12:00:00.000Z', 'America/New_York'); // '2026-03-09T04:00:00.000Z' (EDT)
+ */
+declare function startOfDayInTimezone(iso: ISODateString, timeZone: string): ISODateString;
+/**
+ * Whether two UTC instants fall on the same civil day in the given timezone.
+ * Timezone-safe alternative to comparing `iso.slice(0, 10)`.
+ *
+ * @example
+ * // Seoul is UTC+9, so 03:00 UTC and 14:00 UTC are both on 2026-01-15 KST
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T14:00:00.000Z', 'Asia/Seoul'); // true
+ * // But 17:00 UTC is 02:00 KST on 2026-01-16
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T17:00:00.000Z', 'Asia/Seoul'); // false
+ */
+declare function isSameDayInTimezone(a: ISODateString, b: ISODateString, timeZone: string): boolean;
+/**
+ * "Today" in the given timezone, returned as the UTC ISO string representing that day's midnight.
+ * Prefer this over `new Date()` when the notion of "today" should follow the user's displayed
+ * 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.
+ * Override via the `labels` prop on Root components.
+ */
+interface DatePickerLabels {
+    triggerOpen: string;
+    triggerClose: string;
+    popoverLabel: string;
+    prevMonth: string;
+    nextMonth: string;
+    prevYear: string;
+    nextYear: string;
+    prevDecade: string;
+    nextDecade: string;
+    /** Used by DateTimePicker.Input (present only when DatePickerContext is provided by DateTimePickerRoot) */
+    dateTimeInput?: string;
+}
+interface RangePickerLabels extends DatePickerLabels {
+    startInput: string;
+    endInput: string;
+    presetsGroup: string;
+}
+interface TimePickerLabels {
+    timeInput: string;
+    hourList: string;
+    minuteList: string;
+    amPmToggle: string;
+    hourOption: (hour: number) => string;
+    minuteOption: (minute: number) => string;
+}
+interface DateTimePickerLabels extends DatePickerLabels, TimePickerLabels {
+    dateTimeInput: string;
+}
+declare const DEFAULT_DATEPICKER_LABELS: DatePickerLabels;
+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, 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;
 }
 
 /**
@@ -156,13 +162,16 @@ declare function maxDate(a: ISODateString, b: ISODateString, adapter: DateAdapte
 /**
  * Normalizes a date string to ISO 8601 UTC form.
  * "2026-01-15" → "2026-01-15T00:00:00.000Z"
+ *
+ * Full datetime strings must include a timezone suffix (Z or ±HH:MM).
+ * Strings without a timezone suffix are treated as-is (not matched as datetime).
  */
 declare function normalizeISO(value: string): string;
 /**
  * Parses user input text into an ISO string.
  * Returns null on failure.
  */
-declare function parseInputValue(input: string, format: string, adapter: DateAdapter): string | null;
+declare function parseInputValue(input: string, adapter: DateAdapter): string | null;
 
 /** Time-of-day value (24-hour clock) */
 interface TimeValue {
@@ -219,7 +228,7 @@ declare function isSameTime(a: TimeValue, b: TimeValue): boolean;
  * Formats an ISO datetime as a time string (UTC based).
  * Accepts an adapter for API consistency.
  */
-declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a', _adapter?: DateAdapter): string;
+declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a'): string;
 
 interface WeekdayInfo {
     /** Short name (e.g. "Su", "일") */
@@ -252,4 +261,140 @@ declare function getWeekdayNames(locale?: string, weekStartsOn?: WeekStartsOn):
  */
 declare function formatFullDate(iso: string, locale?: string): string;
 
-export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, type DateAdapter, DateFnsAdapter, type DateRange, type DisabledRule, type ISODateString, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getWeekdayNames, isDateDisabled, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, to12Hour, to24Hour };
+/**
+ * Format a UTC ISO string for display in a specific IANA timezone.
+ * Handles DST transitions correctly. Supports a small set of tokens: `yyyy MM dd HH mm ss`.
+ *
+ * @param iso - UTC ISO 8601 string
+ * @param formatStr - token string (e.g. `"yyyy-MM-dd HH:mm"`)
+ * @param timeZone - IANA zone (e.g. `"America/New_York"`)
+ *
+ * @example
+ * formatInTimezone('2026-03-08T07:30:00.000Z', 'yyyy-MM-dd HH:mm', 'America/New_York');
+ * // → '2026-03-08 03:30'   (post spring-forward EDT)
+ */
+declare function formatInTimezone(iso: ISODateString, formatStr: string, timeZone: string): string;
+/**
+ * UTC offset (minutes east of UTC) at a given UTC instant, as applied by the given timezone.
+ * The offset may differ on either side of a DST transition.
+ *
+ * @example
+ * getTimezoneOffsetMinutes('2026-03-08T06:00:00.000Z', 'America/New_York'); // -300 (EST, UTC-5)
+ * getTimezoneOffsetMinutes('2026-03-08T07:00:00.000Z', 'America/New_York'); // -240 (EDT, UTC-4)
+ * getTimezoneOffsetMinutes('2026-01-15T12:00:00.000Z', 'Asia/Seoul');       //  540 (UTC+9)
+ */
+declare function getTimezoneOffsetMinutes(iso: ISODateString, timeZone: string): number;
+/**
+ * Midnight of the civil date (as observed in `timeZone`) returned as a UTC ISO string.
+ *
+ * Across DST transitions this is the correct way to compute "start of day" — the offset
+ * changes, so the UTC instant of midnight differs before and after the transition.
+ *
+ * @example
+ * startOfDayInTimezone('2026-03-08T12:00:00.000Z', 'America/New_York'); // '2026-03-08T05:00:00.000Z' (EST)
+ * startOfDayInTimezone('2026-03-09T12:00:00.000Z', 'America/New_York'); // '2026-03-09T04:00:00.000Z' (EDT)
+ */
+declare function startOfDayInTimezone(iso: ISODateString, timeZone: string): ISODateString;
+/**
+ * Whether two UTC instants fall on the same civil day in the given timezone.
+ * Timezone-safe alternative to comparing `iso.slice(0, 10)`.
+ *
+ * @example
+ * // Seoul is UTC+9, so 03:00 UTC and 14:00 UTC are both on 2026-01-15 KST
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T14:00:00.000Z', 'Asia/Seoul'); // true
+ * // But 17:00 UTC is 02:00 KST on 2026-01-16
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T17:00:00.000Z', 'Asia/Seoul'); // false
+ */
+declare function isSameDayInTimezone(a: ISODateString, b: ISODateString, timeZone: string): boolean;
+/**
+ * "Today" in the given timezone, returned as the UTC ISO string representing that day's midnight.
+ * Prefer this over `new Date()` when the notion of "today" should follow the user's displayed
+ * 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.
+ * Override via the `labels` prop on Root components.
+ */
+interface DatePickerLabels {
+    triggerOpen: string;
+    triggerClose: string;
+    popoverLabel: string;
+    prevMonth: string;
+    nextMonth: string;
+    prevYear: string;
+    nextYear: string;
+    prevDecade: string;
+    nextDecade: string;
+    /** Used by DateTimePicker.Input (present only when DatePickerContext is provided by DateTimePickerRoot) */
+    dateTimeInput?: string;
+}
+interface RangePickerLabels extends DatePickerLabels {
+    startInput: string;
+    endInput: string;
+    presetsGroup: string;
+}
+interface TimePickerLabels {
+    timeInput: string;
+    hourList: string;
+    minuteList: string;
+    amPmToggle: string;
+    hourOption: (hour: number) => string;
+    minuteOption: (minute: number) => string;
+}
+interface DateTimePickerLabels extends DatePickerLabels, TimePickerLabels {
+    dateTimeInput: string;
+}
+declare const DEFAULT_DATEPICKER_LABELS: DatePickerLabels;
+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, 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 };
 }
@@ -237,14 +357,14 @@ function maxDate(a, b, adapter) {
 
 // src/utils/date.ts
 var ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
-var ISO_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+var ISO_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 function normalizeISO(value) {
   if (!value) return "";
   if (ISO_DATETIME_REGEX.test(value)) return value;
   if (ISO_DATE_REGEX.test(value)) return `${value}T00:00:00.000Z`;
   return value;
 }
-function parseInputValue(input, format, adapter) {
+function parseInputValue(input, adapter) {
   if (!input.trim()) return null;
   const cleaned = input.replace(/\//g, "-").trim();
   if (ISO_DATE_REGEX.test(cleaned)) {
@@ -319,8 +439,8 @@ function generateHours(format = "24h") {
   return Array.from({ length: 24 }, (_, i) => i);
 }
 function generateMinutes(step = 1) {
-  if (step < 1 || step > 60) {
-    throw new Error(`[generateMinutes] step must be between 1 and 60, got ${step}`);
+  if (step < 1 || step > 30) {
+    throw new Error(`[generateMinutes] step must be between 1 and 30, got ${step}`);
   }
   const result = [];
   for (let i = 0; i < 60; i += step) {
@@ -331,7 +451,7 @@ function generateMinutes(step = 1) {
 function isSameTime(a, b) {
   return a.hours === b.hours && a.minutes === b.minutes && a.seconds === b.seconds;
 }
-function formatTimeFromISO(iso, format, _adapter) {
+function formatTimeFromISO(iso, format) {
   const time = getTime(iso);
   if (format === "h:mm a" || format === "h:mm:ss a") {
     const { hours12, period } = to12Hour(time.hours);
@@ -346,30 +466,35 @@ function formatTimeFromISO(iso, format, _adapter) {
 }
 
 // src/utils/locale.ts
+var formatterCache2 = /* @__PURE__ */ new Map();
+function getCachedFormatter(locale, options) {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let fmt = formatterCache2.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options);
+    formatterCache2.set(key, fmt);
+  }
+  return fmt;
+}
+var REFERENCE_YEAR = 2026;
 function getMonthName(month, locale = "en-US") {
-  const date = new Date(Date.UTC(2026, month, 1));
-  return new Intl.DateTimeFormat(locale, { month: "long", timeZone: "UTC" }).format(date);
+  const date = new Date(Date.UTC(REFERENCE_YEAR, month, 1));
+  return getCachedFormatter(locale, { month: "long", timeZone: "UTC" }).format(date);
 }
 function formatMonthYear(year, month, locale = "en-US") {
   const date = new Date(Date.UTC(year, month, 1));
-  return new Intl.DateTimeFormat(locale, {
+  return getCachedFormatter(locale, {
     year: "numeric",
     month: "long",
     timeZone: "UTC"
   }).format(date);
 }
 function getWeekdayNames(locale = "en-US", weekStartsOn = 0) {
-  const shortFormatter = new Intl.DateTimeFormat(locale, {
-    weekday: "short",
-    timeZone: "UTC"
-  });
-  const fullFormatter = new Intl.DateTimeFormat(locale, {
-    weekday: "long",
-    timeZone: "UTC"
-  });
+  const shortFormatter = getCachedFormatter(locale, { weekday: "short", timeZone: "UTC" });
+  const fullFormatter = getCachedFormatter(locale, { weekday: "long", timeZone: "UTC" });
   const days = [];
   for (let i = 0; i < 7; i++) {
-    const date = new Date(Date.UTC(2026, 0, 4 + i));
+    const date = new Date(Date.UTC(REFERENCE_YEAR, 0, 4 + i));
     days.push({
       short: shortFormatter.format(date),
       full: fullFormatter.format(date)
@@ -383,7 +508,7 @@ function getWeekdayNames(locale = "en-US", weekStartsOn = 0) {
 }
 function formatFullDate(iso, locale = "en-US") {
   const date = new Date(iso);
-  return new Intl.DateTimeFormat(locale, {
+  return getCachedFormatter(locale, {
     year: "numeric",
     month: "long",
     day: "numeric",
@@ -391,9 +516,48 @@ function formatFullDate(iso, locale = "en-US") {
     timeZone: "UTC"
   }).format(date);
 }
+
+// src/utils/labels.ts
+var DEFAULT_DATEPICKER_LABELS = {
+  triggerOpen: "Open calendar",
+  triggerClose: "Close calendar",
+  popoverLabel: "Choose date",
+  prevMonth: "Previous month",
+  nextMonth: "Next month",
+  prevYear: "Previous year",
+  nextYear: "Next year",
+  prevDecade: "Previous decade",
+  nextDecade: "Next decade"
+};
+var DEFAULT_RANGEPICKER_LABELS = {
+  ...DEFAULT_DATEPICKER_LABELS,
+  popoverLabel: "Choose date range",
+  startInput: "Start date",
+  endInput: "End date",
+  presetsGroup: "Date range presets"
+};
+var DEFAULT_TIMEPICKER_LABELS = {
+  timeInput: "Time",
+  hourList: "Hour",
+  minuteList: "Minute",
+  amPmToggle: "AM/PM",
+  hourOption: (hour) => `${hour} hours`,
+  minuteOption: (minute) => `${minute} minutes`
+};
+var DEFAULT_DATETIMEPICKER_LABELS = {
+  ...DEFAULT_DATEPICKER_LABELS,
+  ...DEFAULT_TIMEPICKER_LABELS,
+  dateTimeInput: "Date and time"
+};
 export {
+  DEFAULT_DATEPICKER_LABELS,
+  DEFAULT_DATETIMEPICKER_LABELS,
+  DEFAULT_RANGEPICKER_LABELS,
+  DEFAULT_TIMEPICKER_LABELS,
   DateFnsAdapter,
+  civilMidnightFromUtcDay,
   formatFullDate,
+  formatInTimezone,
   formatMonthYear,
   formatTimeFromISO,
   formatTimeString,
@@ -402,8 +566,11 @@ export {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimeInTimezone,
+  getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
+  isSameDayInTimezone,
   isSameTime,
   maxDate,
   minDate,
@@ -411,6 +578,9 @@ export {
   parseInputValue,
   parseTimeString,
   setTime,
+  setTimeInTimezone,
+  startOfDayInTimezone,
   to12Hour,
-  to24Hour
+  to24Hour,
+  todayInTimezone
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kalyx/core",
-  "version": "0.2.2",
-  "description": "Kalyx core — platform-agnostic date logic",
+  "version": "0.4.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",