@kalyx/core 0.2.2 → 0.3.0

package/dist/index.cjs

@@ -20,8 +20,13 @@ 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,
   formatFullDate: () => formatFullDate,
+  formatInTimezone: () => formatInTimezone,
   formatMonthYear: () => formatMonthYear,
   formatTimeFromISO: () => formatTimeFromISO,
   formatTimeString: () => formatTimeString,
@@ -30,8 +35,10 @@ __export(index_exports, {
   getCalendarDays: () => getCalendarDays,
   getMonthName: () => getMonthName,
   getTime: () => getTime,
+  getTimezoneOffsetMinutes: () => getTimezoneOffsetMinutes,
   getWeekdayNames: () => getWeekdayNames,
   isDateDisabled: () => isDateDisabled,
+  isSameDayInTimezone: () => isSameDayInTimezone,
   isSameTime: () => isSameTime,
   maxDate: () => maxDate,
   minDate: () => minDate,
@@ -39,8 +46,10 @@ __export(index_exports, {
   parseInputValue: () => parseInputValue,
   parseTimeString: () => parseTimeString,
   setTime: () => setTime,
+  startOfDayInTimezone: () => startOfDayInTimezone,
   to12Hour: () => to12Hour,
-  to24Hour: () => to24Hour
+  to24Hour: () => to24Hour,
+  todayInTimezone: () => todayInTimezone
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -275,14 +284,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 +366,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 +378,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 +393,35 @@ function formatTimeFromISO(iso, format, _adapter) {
 }
 
 // src/utils/locale.ts
+var formatterCache = /* @__PURE__ */ new Map();
+function getCachedFormatter(locale, options) {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let fmt = formatterCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options);
+    formatterCache.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 +435,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 +443,123 @@ function formatFullDate(iso, locale = "en-US") {
     timeZone: "UTC"
   }).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",
+  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,
   formatFullDate,
+  formatInTimezone,
   formatMonthYear,
   formatTimeFromISO,
   formatTimeString,
@@ -441,8 +568,10 @@ function formatFullDate(iso, locale = "en-US") {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
+  isSameDayInTimezone,
   isSameTime,
   maxDate,
   minDate,
@@ -450,6 +579,8 @@ function formatFullDate(iso, locale = "en-US") {
   parseInputValue,
   parseTimeString,
   setTime,
+  startOfDayInTimezone,
   to12Hour,
-  to24Hour
+  to24Hour,
+  todayInTimezone
 });

package/dist/index.d.cts

@@ -156,13 +156,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 +222,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 +255,94 @@ 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;
+
+/**
+ * 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, 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 };

package/dist/index.d.ts

@@ -156,13 +156,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 +222,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 +255,94 @@ 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;
+
+/**
+ * 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, 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 };

package/dist/index.js

@@ -237,14 +237,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 +319,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 +331,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 +346,35 @@ function formatTimeFromISO(iso, format, _adapter) {
 }
 
 // src/utils/locale.ts
+var formatterCache = /* @__PURE__ */ new Map();
+function getCachedFormatter(locale, options) {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let fmt = formatterCache.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options);
+    formatterCache.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 +388,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 +396,122 @@ function formatFullDate(iso, locale = "en-US") {
     timeZone: "UTC"
   }).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",
+  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,
   formatFullDate,
+  formatInTimezone,
   formatMonthYear,
   formatTimeFromISO,
   formatTimeString,
@@ -402,8 +520,10 @@ export {
   getCalendarDays,
   getMonthName,
   getTime,
+  getTimezoneOffsetMinutes,
   getWeekdayNames,
   isDateDisabled,
+  isSameDayInTimezone,
   isSameTime,
   maxDate,
   minDate,
@@ -411,6 +531,8 @@ export {
   parseInputValue,
   parseTimeString,
   setTime,
+  startOfDayInTimezone,
   to12Hour,
-  to24Hour
+  to24Hour,
+  todayInTimezone
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalyx/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Kalyx core — platform-agnostic date logic",
   "license": "MIT",
   "author": "jiji-hoon96",