@kalyx/core 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,85 @@
 # @kalyx/core
 
-> Platform-agnostic date logic for Kalyx. Types, adapters, and utilities.
+> Platform-independent date logic powering [Kalyx](https://github.com/jiji-hoon96/kalyx). Types, adapters, and UTC-safe utilities.
 
-This package is used internally by `@kalyx/react`. Most users should install `@kalyx/react` directly.
+[![npm](https://img.shields.io/npm/v/@kalyx/core?color=5b4fe1)](https://www.npmjs.com/package/@kalyx/core)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/jiji-hoon96/kalyx/blob/main/LICENSE)
+
+Most users should install [`@kalyx/react`](https://www.npmjs.com/package/@kalyx/react) directly — it re-exports what you need. Install `@kalyx/core` only if you're building your own picker layer or a custom platform adapter.
+
+**📚 Full docs:** [kalyx-docs.vercel.app/docs/api/core](https://kalyx-docs.vercel.app/docs/api/core)
+
+## Install
+
+```bash
+pnpm add @kalyx/core
+```
 
 ## What's inside
 
-- **Types** — `ISODateString`, `DateRange`, `DateAdapter`, `CalendarDay`, `TimeValue`, etc.
-- **DateFnsAdapter** — UTC-based date-fns adapter implementing `DateAdapter` interface
-- **Calendar utils** — `getCalendarDays`, `isDateDisabled`
-- **Time utils** — `setTime`, `getTime`, `parseTimeString`, `to12Hour`, `to24Hour`, `generateHours`, `generateMinutes`
-- **Date utils** — `normalizeISO`, `parseInputValue`
+### Types
+
+```ts
+import type {
+  ISODateString,
+  DisabledRule,
+  DateRange,
+  CalendarDay,
+  CalendarGrid,
+  WeekStartsOn,
+  CalendarOptions,
+  DateAdapter,
+  TimeValue,
+} from '@kalyx/core';
+```
+
+### Adapter
+
+```ts
+import { DateFnsAdapter } from '@kalyx/core';
+// UTC-safe default adapter, built on date-fns v4.
+```
+
+### Calendar utilities
+
+```ts
+import { getCalendarDays, isDateDisabled, minDate, maxDate } from '@kalyx/core';
+```
+
+### Date helpers
+
+```ts
+import { normalizeISO, parseInputValue } from '@kalyx/core';
+```
+
+### Time helpers
+
+```ts
+import {
+  setTime, getTime,
+  parseTimeString, formatTimeString, formatTimeFromISO,
+  to12Hour, to24Hour,
+  generateHours, generateMinutes,
+  isSameTime,
+} from '@kalyx/core';
+```
+
+### Locale helpers
+
+```ts
+import {
+  getMonthName, formatMonthYear,
+  getWeekdayNames, formatFullDate,
+} from '@kalyx/core';
+```
+
+## Principles
+
+- **All dates are ISO 8601 UTC strings** — never `Date` objects.
+- **UTC-only arithmetic** — uses `getUTC*` methods, never local-timezone variants.
+- **Adapter abstraction** — swap date engines by implementing `DateAdapter`.
+- **Pure functions** — zero side effects, fully testable.
 
 ## License
 
-MIT
+[MIT](https://github.com/jiji-hoon96/kalyx/blob/main/LICENSE)

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
 });